--- title: "SDK Changelog" description: "Notable Widget SDK releases, versioning rules, and what's coming in 2.0." canonical: https://glasshome.app/docs/widgets/changelog section: "SDK" updated: 2026-10-08 --- # SDK Changelog Highlights of `@glasshome/widget-sdk`; the entry-by-entry history lives in the [SDK CHANGELOG](https://github.com/glasshome/widget-sdk/blob/main/CHANGELOG.md). The CLI ships separately: see the [CLI changelog](/docs/widgets/cli-changelog). Dash app releases live in the [Dash changelog](/docs/dash/changelog); Hub API changes in the [Hub changelog](/docs/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](/docs/widgets/widget-sdk/materials), 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](/docs/widgets/widget-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; `` 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](/docs/widgets/widget-sdk/config). - `useWidgetDimensions()` replaces `ctx.dimensions()` (deprecated, removed in 2.0). It throws outside `` 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](/docs/widgets/widget-sdk/config). ### 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](/docs/widgets/widget-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](/docs/widgets/widget-sdk/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](/docs/widgets/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](/docs/widgets/widget-migrations). ## Releases [`@glasshome/widget-sdk` on npm](https://www.npmjs.com/package/@glasshome/widget-sdk)