Skip to content
GlassHome
Widget Dev pages

Updated

View MarkdownOpen in ChatGPTOpen in Claude

SDK Changelog

Highlights of @glasshome/widget-sdk; the entry-by-entry history lives in the SDK CHANGELOG. The CLI ships separately: see the CLI changelog. Dash app releases live in the Dash changelog; Hub API changes in the Hub changelog.

Notable SDK releases

1.22: glow and holds

  • A widget’s glow lies softly over the widgets beside it.
  • A hold spends the press, so Android’s long press stays off the card a hold opened.

1.21: materials

  • Parts you draw yourself can match the home’s material: --material-face, --material-raised and the other material variables, and useMaterial() to tell which material it is.
  • Reading --glass-* and a few older --material-* names is deprecated; bun widget build warns, now in .css files too, and names the replacement.
  • A widget with no color of its own takes the material’s fill. Pass tone or color and yours wins.

1.17: sheets, tiles to 8×8

  • The tile anatomy the official widgets use is now yours: Widget.Head, Widget.Hero, Widget.Controls, Widget.Stepper, Widget.Choice, Widget.Action, Widget.Chip, Widget.Backdrop, Widget.Layer, Widget.Glyph, laid out by Widget.Content. See Tiles & Sheets.
  • One scale: --widget-text-value, --widget-text-name, --widget-text-meta, --widget-text-sub, --widget-text-caption, --widget-control-h and the spacing tokens grow with the tile from 1×1 to 8×8.
  • Widget.Action and useConfirm() tick an action that leaves no state; <Widget confirmed> turns the head icon and glyph into a check.
  • Holding a tile opens a sheet of what it cannot show: pass sheet (a render function) to WidgetDialog and the tile holds to open it, wearing the tile’s icon and colour. Edit mode opens settings; the tab row shows only with Developer Mode on.
  • Sheet parts: PanelSection, PanelRows, PanelRow, PanelEntityRow, PanelFacts. New re-exports: SwatchPicker, ColorDisc, TemperatureBar.
  • Tiles take keyboard focus (Enter or Space taps, the context-menu key or Shift+F10 holds), and a hold fills the tile from the finger, firing at 550 ms.
  • field.choice takes icons and field.image takes presets, resolved with imageSrc().
  • useDaylight() needs a sun read in the manifest; the build refuses a widget that uses it without one.

1.10: calendars and service responses

  • useCalendarEvents(id, options?): live events for a calendar entity, pushed by Home Assistant, with a configurable window. Replaces the removed state.conn access.
  • callService(..., { returnResponse: true }) resolves Home Assistant’s service response, so response-only services like todo.get_items work from a widget. Needs Dash 1.1.0-beta.5 on the host: older hosts run the call but resolve undefined.

1.10.3: Windows builds, ui installs itself

  • Builds on Windows failed at validation (“Received protocol ‘c:’”): the introspection step imported the bundle by filesystem path. Fixed.
  • @glasshome/ui is a required peer again. 1.10.0 marked it optional, so a fresh project stopped receiving it and every build failed with “@glasshome/ui is required to build widgets”. Run bun widget upgrade (CLI 0.11+) or bun update @glasshome/widget-sdk.

1.9: richer config, measured dimensions

  • field.list(item, opts): add/remove/reorder lists of sub-forms, and field.variants(discriminator, variants): discriminated-union configs. See the Config API.
  • useWidgetDimensions() replaces ctx.dimensions() (deprecated, removed in 2.0). It throws outside <Widget> instead of silently reporting a zero-size box.
  • 21 @glasshome/ui primitives re-export through the SDK barrel, so sdkVersion gates them; direct @glasshome/ui imports are deprecated.
  • Builds write the config schema, defaultConfig, examples, and configVersion into the manifest, and validate examples against your schema before publish.

1.4: the Config API

  • defineConfig + field.* replace hand-written zod schemas (zod stays available as an escape hatch via the SDK’s z re-export). About 55KB lighter per widget.
  • widgetFields.* and raw z.object configs deprecated; bun widget migrate config auto-migrates most widgets. See Config API.

1.2: scoped entity pickers

  • Entity fields accept { deviceClass } to scope the picker (for example temperature sensors only).

1.0: the security release

  • Widgets moved into an isolated, permission-scoped sandbox: shadow-root rendering, capability declarations, no direct HA access. Migration checklist: Upgrading to SDK 1.0.

Coming in 2.0 (breaking)

  • widgetFields and the raw-zod config path are removed; defineConfig + field.* become the only way to declare config. Migrate now with bun widget migrate config.
  • ctx.dimensions() and direct @glasshome/ui imports are removed (deprecated since 1.9; builds already warn).
  • Reading --glass-* and the retired --material-* names (--material-depth, --material-hue and the others listed on Materials) stops working (deprecated since 1.21; builds warn).

How versioning works

  • Widget SDK (@glasshome/widget-sdk) ships on npm. Each widget declares an sdkVersion range in its manifest; the registry serves each dashboard the newest compatible build. See Widget SDK.
  • Widget config version (configVersion) is a per-widget integer you bump when your widget’s config shape has breaking changes. See Config Migrations.

Releases

@glasshome/widget-sdk on npm