A ~55kb boilerplate card for Home Assistant.
- 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)
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>
);
};
...
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>
);
};
...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 onend: 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>
);
};
...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>
);
};
...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>
);
};
...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>
);
};
...