zupre

A ~55kb boilerplate card for Home Assistant.

Stack:

• TypeScript
• zustand (state management)
• styled-components (styles)
• custom-card-helpers (Home Assistant utils + types)
• home-assistant-js-websocket (Home Assistant types)
• webpack (build system)
• ESLint (linter)
• Husky (pre-commit hooks)

Hooks

• useEntity
• useEntities
• useHistory
• useUser
• useHass
• useConfig

useEntity(entityId: string)

---

Retrieves an entity by ID from the Home Assistant state. The entity will be undefined if the state of HA is not loaded or if the entity does not exist.

Returns: HassEntity | undefined

Example:

...

const Card = () => {
  const sun = useEntity('sun.sun'); // sun: HassEntity | undefined

  return (
    <div style={{ padding: '1rem' }}>
      <p>{ sun?.attributes.friendly_name }</p>
      <p>
        State:
        {' '}
        { sun?.state }
      </p>
    </div>
  );
};

...

useEntities(entityIds: string[])

---

Retrieves a record of entities by their IDs.

Returns: Record<string, HassEntity | undefined>

Example:

...

const Card = () => {
  const lights = useEntities([
    'light.lamp',
    'light.ceiling',
    'light.outside',
  ]); // lights: Record<string, HassEntity | undefined>

  return (
    <div style={{ padding: '1rem' }}>
      <pre>
        { JSON.stringify(lights, null, 2) }
      </pre>
    </div>
  );
};

...

useHistory(entityId: string, config?: HistoryConfig)

---

Retrieves the history for an entity's state. The optional config parameter takes two fields:

• start: Date - the starting time/date to base the history on
• end: Date - the ending time/date to base the history on

By default, this period is the last 24hrs.

Types:

type Datum = { last_changed: Date, state: string }

interface HistoryConfig = {
  start?: Date;
  end?: Date;
}

Returns: { history: Datum[]; entity: HassEntity | undefined }

Example:

...

const Card = () => {
  const { history, entity } = useConfig(); // { history: Datum[]; entity?: HassEntity }

  return (
    <div style={{ padding: '1rem' }}>
      <p>{ entity?.attributes.friendly_name }:</p>
      <p>{ entity?.state }</p>
      <p>
        Changed
        {' '}
        { history.length }
        {' '}
        times.
      </p>
    </div>
  );
};

...

useUser()

---

Retrieves the currently signed in user and its corresponding entity.

Returns: (CurrentUser & { entity: HassEntity | undefined }) | undefined

Example:

...

const Card = () => {
  const user = useUser(); // user: (CurrentUser & { entity: HassEntity | undefined }) | undefined

  return (
    <div style={{ padding: '1rem' }}>
      <p>{ user?.name }</p>
      <img src={user?.entity?.attributes.entity_picture || ''} />
    </div>
  );
};

...

useHass()

---

Retrieves current Home Assistant instance. Useful for API/service calls.

Returns: HomeAssistant | undefined

Example:

...

const Card = () => {
  const hass = useHass(); // hass: HomeAssistant | undefined

  return (
    <div style={{ padding: '1rem' }}>
      <button
        onClick={
          hass
            ? hass.callService('homeassistant', 'restart')
            : () => {}
        }
      >
        Restart
      </button>
    </div>
  );
};

...

useConfig()

---

Retrieves the current config of the card. Note that Config is a type should be customized to the given card's use case.

Returns: Config | undefined

Example:

...

const Card = () => {
  const config = useConfig(); // config: Config | undefined

  return (
    <div style={{ padding: '1rem' }}>
      <p>{ config?.type }</p>
    </div>
  );
};

...