dangreco / zupre

HA boilerplate card using Zustand, Preact, Styled Components

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

...

zupre's Issues

Styled Components Issue

Hi,

Attempting to use your boiler plate code but running in to an issue with the styled components, seems to be related to the target={this}.

The error: An error occurred. See https://git.io/JUIaE#17 for more information..

This is on a fresh HA dev install in docker and making no changes to your boilerplate code.

Zustand store collision

Issue

When there's multiple of the same card on one dashboard, the Zustand states interfere with one another, because they are global singletons.

Fix

Switch to React Context and use separate providers for config and hass (to prevent unnecessary config re-renders when hass updates).
I did this in my project and it fixed the issue. If you are interested, I could create another pull request for this change; or correct me if I did something wrong please. Thanks!