@mosaic-home/ha-widgets

Home Assistant widgets written once: for each widget type, which entities and options it takes, what it needs fetched, and what it shows. What it shows is a View, plain data that any renderer can draw. This package has a React renderer; @mosaic-home/capacitor-ha-widgets draws the same views on the Android home screen.

Part of the Mosaic Home Assistant kit.

Widget types

Light, Switch, Thermostat, Sensor, Graph, Weather, Media player, Button, Blinds and doors, Lock, Fan, Camera, Several entities, People, To-do list, Calendar, Ask the assistant, Lights on, Doors and windows, Batteries, Number, Choice, Timer, Vacuum and mower, Alarm, and Entity (any entity). WIDGET_TYPES lists them in gallery order; typesForEntity gives the types that fit an entity, best first.

Install

npm install @mosaic-home/ha-widgets
npm install react      # only for the React renderer

Use

import { buildView, needsFor, newConfig, type WidgetContext, type WidgetData } from '@mosaic-home/ha-widgets';
import { iconPath } from '@mosaic-home/ha-widgets/icons';
import { WidgetView } from '@mosaic-home/ha-widgets/react';
import '@mosaic-home/ha-widgets/react.css';

const config = newConfig('light', ['light.kitchen']);
const context: WidgetContext = { now: Date.now(), locale: 'en-GB', temperatureUnit: '°C' };

// What to fetch: here one state. Others are a whole domain, history, a service's response or the assistant's answer.
console.log(needsFor(config, context)); // [{ kind: 'state', entityId: 'light.kitchen' }]

const data: WidgetData = {
  states: {
    'light.kitchen': { entity_id: 'light.kitchen', state: 'on', attributes: { friendly_name: 'Kitchen', brightness: 153 } },
  },
};
const view = buildView(config, data, context);

export function KitchenLight() {
  return <WidgetView view={view} size={{ width: 2, height: 1 }} icon={iconPath} onAction={(action) => console.log(action)} />;
}

onAction receives what a tap asks for: call a service, ask the assistant, refresh, or open the app. The app runs it against Home Assistant (for example with @mosaic-home/ha-client) and builds the view again. buildView never throws: missing entities and unknown types become a view that says so.

Entry points

| Import | What it is | |---|---| | @mosaic-home/ha-widgets | The catalogue, needsFor, buildView, entity and formatting helpers, and the types | | @mosaic-home/ha-widgets/react | WidgetView, the React renderer | | @mosaic-home/ha-widgets/react.css | Its styles | | @mosaic-home/ha-widgets/icons | iconPath: an SVG path for a Material Design Icons name. Brings in the whole icon set | | @mosaic-home/ha-widgets/engine.js | Everything in one classic script for engines without modules or a DOM; it sets globalThis.MosaicWidgets with needs, build and types, each taking and returning JSON |

What it needs

Nothing but @mdi/js (installed with it). React 18 or newer only if you use the React renderer.

Licence

Apache-2.0. Icons are Material Design Icons from @mdi/js (Apache-2.0).