Empty states

Sooner or later, every list is empty. Someone just installed Home Assistant, a search finds nothing, a filter hides everything. An empty state turns that blank space into a clear message: what is going on, and what people can do about it.

Use an empty state when a screen, a panel, or a list has finished loading and has nothing to show. There are two kinds, and they need different words:

• Nothing yet: people have not picked or created anything. Tell them what to do to get started.
• No results: there is data, but the current search or filter matches none of it. Tell them what to change.

The history panel shows both. Before you pick anything, it says Nothing to show yet: "Select areas, devices, entities or labels to see their history". When your selection has no history, it says No results found: "No history for the current selection. Try changing the targets, filters, or time range."

Pickers make the same split: one text for a list that has no items at all, and another for a search that matches nothing.

Don't show an empty state while the content is still loading. Show a loading state until you know the list is empty.

The frontend has one component for this: ha-empty-state. It centers its content in the space it gets, up to 500 pixels wide, with:

• An icon on top, 64 pixels, in the secondary text color
• A heading that says what is going on
• An optional description that says why, or what to do next
• Optional actions below it, like a button to add the first item

• The heading is short and plain: No results found, Nothing to show yet.
• The description says what people can do: "Try changing the targets, filters, or time range."
• When there is one clear next step, offer it as a button, with a label that says what it does.

See Messages for more on the words.

• The heading is a real heading (h2), so screen reader users can find it.
• The icon is decoration. The heading and description carry the message on their own.

• ha-empty-state, in src/components/ha-empty-state.ts of the frontend.
• Button, for the next step
• Entity picker and the other pickers, for their own empty and no match texts

html`
  <ha-empty-state
    .icon=${mdiChartBoxOutline}
    .heading=${this.hass.localize("ui.panel.history.no_results_title")}
    .description=${this.hass.localize("ui.panel.history.no_results")}
  ></ha-empty-state>
`;

Put actions, like an ha-button, in the default slot. Set --ha-empty-state-icon-size to change the size of the icon.