How dashboards work

A dashboard is a page of cards, and the part of the frontend most people see most. Under the hood, it is a configuration, made of views, sections, cards, and badges, that the frontend turns into elements.

• A dashboard has views. A view has sections, and sections have cards, or cards directly, depending on the view type.
• Each card type is a web component, like hui-tile-card, loaded when a dashboard uses it.
• A dashboard is stored in Home Assistant, or written in YAML.
• A strategy generates a dashboard, or a view, from the home itself.
• Custom cards are web components loaded from a JavaScript file.

A dashboard is a configuration, like this:

views:
  - title: Home
    type: sections
    sections:
      - type: grid
        cards:
          - type: tile
            entity: light.kitchen

The frontend reads it, and creates an element for each part: a view, a section, a hui-tile-card with its configuration. Card types load when a dashboard first uses them.

• Cards show and control things. Their configuration says what. Many have a visual editor.
• Badges are small pills at the top of a view.
• Card features add controls to a card, like a brightness slider.

The cards and their configuration options are in dashboard cards, with live examples.

• In storage: the default. Users edit it in the UI, and Home Assistant saves it with the WebSocket API.
• In YAML: the user writes it in a file. The UI can't edit it.

A strategy is code that generates a dashboard, a view, or a section, instead of a fixed configuration. The dashboard users see when they first open Home Assistant is one: it builds itself from the areas and devices, and stays up to date when something is added. Users can take control of a generated dashboard, and edit its configuration from there.

Cards, badges, views, and strategies can also come from outside the frontend, as web components loaded from a JavaScript file and used with a custom: type, like custom:my-card. They get the same hass object and configuration as the built-in ones. How to build them is in custom cards and more.

• Start with your first frontend contribution.
• Build your own card, badge, or strategy: custom cards and more.
• The built-in cards and how they should look and behave: dashboard cards in the Design area.