Widget SDK

@glasshome/widget-sdk (on npm) provides defineWidget, the Config API (defineConfig + field.*), composable UI components, reactive hooks, the Home Assistant data layer, and theming utilities for SolidJS widgets.

The runtime constant SDK_VERSION equals the installed package version; the host compares it against each widget’s manifest.sdkVersion range.

This page is the guide. For every public export across the three entry points, see the API Reference.

On this page

• defineWidget and manifest fields
• widgetFields and the complete widget example
• <Widget>: variants and slot subcomponents
• The <WidgetDialog> settings dialog
• Hooks, Home Assistant data & services, the EntityView shape
• Errors and empty states, theming, entity utilities, build tooling

defineWidget

The entry point for every widget: a manifest (metadata), an optional Zod config schema, an optional migrate function, and a SolidJS component.

function defineWidget<C = Record<string, unknown>>(
  definition: WidgetDefinition<C>
): WidgetDefinition<C>

WidgetDefinition<C> shape:

interface WidgetDefinition<C = Record<string, unknown>> {
  manifest: WidgetManifest;
  configSchema?: ZodType<C, unknown>;
  migrate?: (config: Record<string, unknown>, fromConfigVersion: number) => Record<string, unknown>;
  component: (props: { config: C }) => any;
}

Providing configSchema auto-populates manifest.schema (JSON Schema) and manifest.defaultConfig. Types derive via z.infer; the dashboard renders the edit form from the schema.

Manifest fields

The runtime loads the inline manifest in defineWidget; the CLI reads src/<name>/manifest.json for build and publish metadata (bun widget upgrade writes sdkVersion back to that file). Keep the two in sync: the build step warns on schema drift.

widgetFields

Pre-built Zod field helpers; each attaches metadata so the dashboard renders the right form control.

See the Config API for the full field.* surface (field.text, field.number, field.toggle, field.choice, field.stringList, field.group) and type inference with Infer.

Complete widget example

A working example mirroring the official @glasshome widgets: config schema, entities bound from config via useEntities, group aggregation via useWidgetEntityGroup, a tap-to-toggle gesture, and a schema-driven settings dialog. Note that you bind entities yourself from the ids the user picked in config; there is no hidden injection.

// src/my-lights/index.tsx
import {
  defineWidget,
  Widget,
  WidgetDialog,
  useEntities,
  useService,
  useWidgetContext,
  useWidgetDialog,
  useWidgetEntityGroup,
  useWidgetGestures,
  widgetFields,
} from "@glasshome/widget-sdk";
// Dialog chrome (ResponsiveDialog, Button, SchemaForm) is injected, not bundled by the SDK.
// The official widgets re-export these from @glasshome/ui as a `widgetDialogProps` object.
import {
  Button,
  ResponsiveDialog,
  ResponsiveDialogContent,
  ResponsiveDialogDescription,
  ResponsiveDialogHeader,
  ResponsiveDialogTitle,
  SchemaForm,
} from "@glasshome/ui/solid";
import { onCleanup } from "solid-js";
import { z } from "zod";

const configSchema = z.object({
  title: widgetFields.title(),
  entityIds: widgetFields.entityIds("light"),
});

type Config = z.infer<typeof configSchema>;

function MyLightsWidget(props: { config: Config }) {
  const ctx = useWidgetContext();
  const { openDialog, setShowDialog, dialogProps } = useWidgetDialog();
  const { toggle } = useService();

  // Bind the entities the user picked in config. Reactive: updates when state changes.
  const entities = useEntities(() => props.config.entityIds);

  const { aggregatedData, emptyState, hasEntities } = useWidgetEntityGroup({
    entities,
    aggregationMode: () => "light",
    emptyStateConfig: {
      icon: <span>💡</span>,
      title: "No lights",
      message: "Hold to configure",
    },
  });

  const lightData = () => aggregatedData();
  const isOn = () => lightData()?.isOn ?? false;

  const gestures = useWidgetGestures(() => ({
    tap: () => toggle(entities().map((e) => e.id)),
    hold: { action: openDialog },
  }));
  onCleanup(gestures.dispose);

  return (
    <>
      <Widget
        gestures={gestures}
        variant="classic-glass"
        tone={isOn() ? "accent" : "neutral"}
        emptyState={emptyState()}
        loading={!hasEntities()}
      >
        <Widget.Title>{props.config.title || "Lights"}</Widget.Title>
        <Widget.Status>{isOn() ? "On" : "Off"}</Widget.Status>
        <Widget.Value>
          {lightData() ? `${lightData()!.onCount}/${lightData()!.totalCount}` : ""}
        </Widget.Value>
      </Widget>
      <WidgetDialog
        {...dialogProps}
        ResponsiveDialog={ResponsiveDialog}
        ResponsiveDialogContent={ResponsiveDialogContent}
        ResponsiveDialogHeader={ResponsiveDialogHeader}
        ResponsiveDialogTitle={ResponsiveDialogTitle}
        ResponsiveDialogDescription={ResponsiveDialogDescription}
        Button={Button}
        SchemaForm={SchemaForm}
        title="Lights"
        maxWidth="lg"
        configSchema={configSchema}
        config={props.config}
        onConfigSave={(config) => {
          ctx.updateConfig(config);
          setShowDialog(false);
        }}
      />
    </>
  );
}

export default defineWidget<Config>({
  manifest: {
    name: "My Lights",
    description: "Toggle a group of lights",
    icon: "mdi:lightbulb-group",
    minSize: { w: 1, h: 1 },
    maxSize: { w: 4, h: 4 },
    sdkVersion: "^1.0.0",
    capabilities: [{ domain: "light", access: "control" }],
  },
  configSchema,
  component: MyLightsWidget,
});

Widget component

<Widget> is the main container: context, gesture handling, theming, and base styling.

Props

interface WidgetProps {
  variant?: string | WidgetVariantConfig;
  tone?: Tone;           // semantic color: resolves to --widget-color
  color?: string;        // CSS color override for --widget-color (overrides tone)
  colorTo?: string;      // second gradient stop (--widget-color-to)
  gradient?: string;     // full CSS gradient (overrides auto-shell)
  loading?: boolean;
  class?: string;
  isEditMode?: boolean;
  onDelete?: () => void;
  emptyState?: { icon?: JSX.Element; title?: string; message?: string };
  gestures?: GestureHandlers; // return value of useWidgetGestures(...)
  children?: JSX.Element;
}

Pass the return value of useWidgetGestures(...) to gestures, not a plain object.

Variants

variant picks a pre-built look (shell background, blur, layout defaults, hover/active behavior): a built-in id string or a full WidgetVariantConfig object. The SDK ships three:

<Widget variant="classic-glass" tone="accent">…</Widget>

WidgetVariantConfig is exported from the SDK for fully custom looks. Tone and color props (Theming, Styling) layer on top of whichever variant you choose.

Slot subcomponents

Widget.SliderFill is also exported standalone as WidgetSliderFill (same component). Pass isDragging so the fill tracks the finger 1:1 while dragging (drops the transition). See Animation.

Component props

Every widget component receives one prop, { config: C }, where C is the type passed to defineWidget<C>. The host parses, migrates, and validates the saved config first, so config always matches your current schema type.

Hooks

useWidgetContext()

Returns ReactiveWidgetContext. Must be called inside the <Widget> render tree.

interface ReactiveWidgetContext {
  isEditMode: () => boolean;
  updateConfig: (config: Record<string, unknown>) => void;
  dimensions: () => { width: number; height: number }; // CSS px, (0,0) before first layout
  registerDialogOpener?: (open: ((tab?: string) => void) | null) => void;
}

useWidgetEntityGroup(options)

Aggregates one or many entities with built-in aggregation presets and empty-state support.

function useWidgetEntityGroup<TData = unknown>(
  options: UseWidgetEntityGroupOptions<TData>
): UseWidgetEntityGroupResult<TData>

Options:

Return value:

LightGroupResult includes: isOn, isUnavailable, brightness (0-255), brightnessPercent (0-100), color, onCount, totalCount, description.

useWidgetDialog(defaultTab?)

Controls the widget settings dialog. defaultTab defaults to "controls".

interface WidgetDialogReturn {
  showDialog: () => boolean;
  setShowDialog: (open: boolean) => void;
  openDialog: (tab?: string) => void;
  closeDialog: () => void;
  activeTab: () => string;
  setActiveTab: (tab: string) => void;
  dialogProps: {
    open: boolean;
    onOpenChange: (open: boolean) => void;
    activeTab: string;
    onActiveTabChange: (tab: string) => void;
  };
}

Spread dialogProps onto <WidgetDialog> to wire open/close and tab state automatically.

WidgetDialog component

<WidgetDialog> is the settings/detail dialog: a tabbed panel that can host device controls, a schema-driven config editor, and a debug view. It renders no chrome of its own; you inject the dialog/button/form components as props.

Injected UI components (required)

These have no defaults; the dialog will not render without them. Import from @glasshome/ui/solid:

Content props

Config-only widgets pass just configSchema + config + onConfigSave; control widgets add controlsContent. See the complete example for the wiring.

useWidgetGestures(config, orientation?)

Tap, hold, and slide gestures on any pointer type.

function useWidgetGestures(
  config: () => GestureConfig,
  orientation?: () => "horizontal" | "vertical" | "square"
): GestureHandlers

Both arguments are SolidJS accessors; orientation is optional and defaults to horizontal.

interface GestureConfig {
  tap?: () => void;
  hold?: { action: () => void; delay?: number }; // delay in ms, default 300
  slide?: {
    value: number;
    onChange: (value: number) => void;
    min?: number; max?: number;
    orientation?: "auto" | "horizontal" | "vertical";
    activationDelay?: number;
  };
}

GestureHandlers (returned value) carries onPointerDown, onPointerMove, onPointerUp, onPointerCancel, onPointerEnter, bindElement, touchAction, and dispose. Pass the whole object to <Widget gestures={...} />. Call dispose() in onCleanup.

useReducedMotion()

Reactive prefers-reduced-motion accessor, () => boolean; false when matchMedia is unavailable (SSR-safe).

useIntersectionPause(elAccessor)

Returns () => boolean: true while the element (passed as an accessor) is off-screen; false when IntersectionObserver is unavailable (SSR-safe).

Home Assistant data & services

Import all Home Assistant hooks from @glasshome/widget-sdk, never from @glasshome/sync-layer directly (a direct import fails the build and would bundle a second, disconnected store). Read hooks are SolidJS accessors backed by the host’s live store, so UI stays reactive with no WebSocket state to manage. Reads and service calls are checked against your declared capabilities.

Reading entities

import { useEntity, useEntities } from "@glasshome/widget-sdk";

function Thermostat(props: { config: Config }) {
  const climate = useEntity(() => props.config.entityId);
  const temp = () => climate()?.attributes.current_temperature;
  return <Widget.Value>{temp() ?? "—"}</Widget.Value>;
}

The EntityView shape

Every read hook returns EntityView objects. The most-used fields:

EntityView is exported as a type from the SDK for your own annotations.

Connection & locale

Calling services

useService() returns a capability-routed service caller plus shortcuts that take an entity id (or array) and optional service data:

import { useService } from "@glasshome/widget-sdk";

function LightToggle(props: { config: Config }) {
  const { toggle, turnOn, callService } = useService();

  return (
    <Widget gestures={useWidgetGestures(() => ({ tap: () => toggle(props.config.entityId) }))}>
      {/* turnOn("light.x", { brightness_pct: 80 }) */}
      {/* callService("light", "turn_on", { brightness_pct: 80 }, { entity_id: "light.x" }) */}
    </Widget>
  );
}

callService(domain, service, data?, target?) is the general form; it resolves to Promise<void>. The host validates the call against your granted capabilities before forwarding it.

Errors and empty states

• Config schema parse failure. If the stored config fails Zod validation after migration, the dashboard falls back to configSchema.parse({}) (all-defaults), then to {}. No error is shown to the user; handle missing/default config gracefully.
• Missing entities. Pass an emptyStateConfig to useWidgetEntityGroup. When hasEntities() is false, emptyState() returns the config object; pass it to <Widget emptyState={emptyState()}> to render the built-in empty state UI.
• Component throw. A render throw is caught by an ErrorBoundary: after one crash, a retryable error card with a Retry button; after three crashes (configurable in the Dash host), a permanent “disabled” card until the page is refreshed.

Theming

Widgets inherit the dashboard theme automatically and render in an isolated shadow root with their own CSS bundle. The essentials:

• Use the tone prop on <Widget> for semantic color (tone="accent"), or color/colorTo/gradient for a custom shell.
• isDark() returns the current theme as a boolean for logic; dark: Tailwind variants work in markup.
• The SDK also exports injectTokens, Tone, and ToneSchema.

The full styling model (Tailwind, your own CSS, theme variables, container queries, animation): Styling & Animation.

Entity utilities

Build tooling

The scaffolded vite.config.ts wires this up automatically. Two entrypoints for custom setups:

@glasshome/widget-sdk/vite

@glasshome/widget-sdk/schemas

Zod schemas for validating manifests and publish payloads. Used by the CLI and Hub.

Re-exported from the canonical @glasshome/widget-contract package shared by the SDK, CLI, Hub, and Dash, so the same schema validates a manifest everywhere.

formatSchemaError and WidgetManifestSchema are also available from the SDK main entry (@glasshome/widget-sdk) for convenience.