API Reference#

Every public export of @glasshome/widget-sdk, with signatures, by entry point. This is the exhaustive reference; the Widget SDK guide walks the important APIs with worked examples. Anything not listed here is internal and may change without notice.

Entry points#

Most types named below are exported too, so you can annotate your own code. Reactive values follow SolidJS conventions: Accessor<T> is () => T, and any argument typed Accessor<X> | X accepts a plain value or an accessor.

@glasshome/widget-sdk (main entry)#

Core#

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

Declares a widget. When definition.configSchema is present, defineWidget auto-populates manifest.schema (JSON Schema) and manifest.defaultConfig from it. See the guide.

const SDK_VERSION: string  // the installed package version, e.g. "1.2.0"

The host compares SDK_VERSION against each widget’s manifest.sdkVersion range.

Components#

Widget carries its slots as static members (Widget.Icon, Widget.Title, …); the same components are also exported standalone.

Widget hooks#

function useWidgetContext(): ReactiveWidgetContext

Reactive widget context. Must be called inside the <Widget> 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;
  callService?: ServiceCallFn;  // present when capability-routed by the host
}

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

Aggregate one or many entities with presets + empty state. Options take reactive entities: Accessor<EntityView[]>, an aggregationMode ("light" \| "sensor" \| "switch" \| "binary-sensor" \| "none") or a custom calculateGroupData, plus emptyStateConfig, sensorGroupType, allEntitiesMode, and minEntities. Returns entities, groupData, aggregatedData, emptyState, hasEntities, and count accessors. Full tables in the guide.

function useWidgetDialog(defaultTab = "controls"): WidgetDialogReturn

Open/close + active-tab state for WidgetDialog. Returns showDialog, setShowDialog, openDialog, closeDialog, activeTab, setActiveTab, and a dialogProps bag to spread onto <WidgetDialog>.

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

Tap, hold, and slide gestures for any pointer. GestureConfig = { tap?, hold?: { action, delay? }, slide?: { value, onChange, min?, max?, orientation?, activationDelay? } }. Pass the returned GestureHandlers to <Widget gestures={…} />; call .dispose() in onCleanup.

function useReducedMotion(): Accessor<boolean>      // prefers-reduced-motion; false if unavailable (SSR-safe)
function useIntersectionPause(el: Accessor<Element | undefined>): Accessor<boolean>  // true while off-screen

Config schema helpers#

const widgetFields: {
  title(): ZodType;                                              // text input "Title"
  entityIds(domain: string, opts?: { deviceClass?: string }): ZodType;     // multi-select entity picker
  singleEntity(domain: string, opts?: { deviceClass?: string }): ZodType;  // single-select entity picker
  areaId(): ZodType;                                            // area picker dropdown
}

Pre-built Zod fields with .meta() annotations the host’s form renderer reads. For anything else use Zod directly (z.boolean() → switch, z.enum() → dropdown). See widgetFields.

Home Assistant data hooks#

Reactive accessors over the host’s live store. Each entityId arg accepts a string or an accessor. Reads are checked against your declared capabilities.

Connection & locale hooks#

Services#

function useService(): {
  callService: ServiceCallFn;
  turnOn:  (entityId: string | string[], data?: Record<string, unknown>) => Promise<void>;
  turnOff: (entityId: string | string[], data?: Record<string, unknown>) => Promise<void>;
  toggle:  (entityId: string | string[], data?: Record<string, unknown>) => Promise<void>;
}

type ServiceCallFn = (
  domain: string,
  service: string,
  data?: Record<string, unknown>,
  target?: { entity_id?: string | string[] }
) => Promise<void>;

Inside a host-mounted widget these route through the host’s capability check (a control grant is required); in preview/tests they fall back to direct sync-layer calls. useTurnOn(), useTurnOff(), and useToggle() each return just the one shortcut.

Entity utilities#

LightGroupResult: isGroup, state, isOn, isUnavailable, brightness (0–255), brightnessPercent (0–100), color, onCount, totalCount, description. SensorGroupResult: isGroup, state, numericValue (number \| null), isUnavailable, unit?, description, memberValues?. SensorGroupType: "min" \| "max" \| "mean" \| "median" \| "sum" \| "last" \| "range" \| "product" \| "std_dev".

Theming & charts#

Tone: "success" \| "warning" \| "danger" \| "info" \| "neutral" \| "accent".

Validation re-exports#

Convenience re-exports also available from /schemas.

Lower-level data exports#

Advanced building blocks the hooks are built on. Most widgets never touch these.

Types (main entry)#

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;
}

interface WidgetManifest {
  name: string;
  description?: string;
  minSize: GridSize;          // { w, h }
  maxSize: GridSize;
  defaultSize?: GridSize;
  sdkVersion: string;
  icon?: string;
  capabilities?: CapabilityGrant[];
  configVersion?: number;
  schema?: object;            // auto-populated from configSchema; do not set
  defaultConfig?: Record<string, unknown>;  // auto-populated; do not set
  cssUrl?: string;            // set by the build
}

interface GridSize { w: number; h: number }

Other exported types: WidgetContext, ReactiveWidgetContext, EntityView (see the shape), AreaView, WidgetVariantConfig, WidgetStyles, Tone, SvgColorKey, GestureHandlers, AggregationPreset, SensorGroupType, LightGroupResult, SensorGroupResult, UseWidgetEntityGroupOptions, UseWidgetEntityGroupResult, WidgetDialogProps, WidgetDialogTab, WidgetDialogReturn, ServiceCallFn.

@glasshome/widget-sdk/schemas#

Zod schemas re-exported from the canonical @glasshome/widget-contract package (the single source of truth shared by the SDK, the CLI, the Hub, and Dash), so the same definitions validate a manifest everywhere.

@glasshome/widget-sdk/vite#

Build plugins and helpers for vite.config.ts. The scaffolded config wires these automatically; reach for them only for custom setups. See Build tooling.

BuildWidgetsOptions / GlasshomeWidgetsOptions: { srcDir?, outDir?, plugins?, viteConfig?, only? }. GlasshomeWidgetOptions: { entry?, … }. All three types are exported.

Dialog UI components (from @glasshome/ui)#

WidgetDialog takes its chrome as props. These are not SDK exports; import them from @glasshome/ui/solid and pass them in (keep @glasshome/ui as a dependency). See WidgetDialog component.

ResponsiveDialog, ResponsiveDialogContent, ResponsiveDialogHeader, ResponsiveDialogTitle, ResponsiveDialogDescription, Button, SchemaForm (SchemaForm is required only when you use configSchema).