Skip to content

Page Templates

tempus2016 edited this page Nov 9, 2026 · 2 revisions

Page Templates (v2.9.0+)

A template can be a whole dashboard. dashboard: is a kind of its own beside card:, row:, badge:, element: and group:, and a dashboard whose strategy says page: becomes whatever that template builds: its title, its views, the cards in them, and any other setting a dashboard's configuration holds.

That is for the house with three wall tablets, or the same layout on a holiday cottage and at home: the dashboard is written once, as a template, and each copy of it is a few lines naming the template and saying what is different.

On this page:


The smallest page

Page templates are read by the dashboard strategy, because the strategy is the one place Home Assistant hands a whole dashboard to a card. On a dashboard of your own, open the pencil, then ⋮ → Raw configuration editor, and replace what is there with:

strategy:
  type: custom:decluttering-card-plus
  decluttering_templates:
    hello_page:
      dashboard:
        title: '[[house]]'
        views:
          - title: Home
            cards:
              - type: markdown
                content: Hello from [[house]].
  page:
    template: hello_page
    variables:
      house: The Old Barn

A dashboard with one view, Home, holding one card that says Hello from The Old Barn

That is the whole of it: a template whose content is under dashboard: rather than card:, and a page: that names it and gives it values. What is under dashboard: is what you would otherwise have written in the raw configuration editor, with placeholders wherever a copy of the dashboard might differ. Change house and save, and the dashboard is written again.

A dashboard from a template

The same shape carries a real dashboard. A welcome view, then a view per area with a light in it, from one template:

strategy:
  type: custom:decluttering-card-plus
  decluttering_templates:
    house_page:
      description: The whole house, a welcome view and then a view per area
      variables:
        - name: house
        - name: domain
          default: light
      dashboard:
        title: '[[house]]'
        views:
          - title: Home
            path: home
            cards:
              - type: markdown
                content: |-
                  ## Welcome to [[house]]
                  Every area with a [[domain]] in it has a view of its own.
          - for_each_from:
              areas: true
              with:
                domain: '[[domain]]'
              require: entities
            view:
              title: '[[area]]'
              path: '[[area_id]]'
              type: sections
              max_columns: 2
              sections:
                - type: grid
                  cards:
                    - type: heading
                      heading: '[[area]]'
                    - type: custom:decluttering-card-plus
                      template: entity_tile
                      for_each_from:
                        area: '[[area_id]]'
                        domain: '[[domain]]'
    entity_tile:
      card:
        type: tile
        entity: '[[entity]]'
  page:
    template: house_page
    variables:
      - house: The Old Barn

A dashboard titled The Old Barn with a Home tab and one tab per area that has a light

The Home view, and a tab for every area with a light in it.

page: takes the template's name and the variables: to build it with, as a list of one-name entries or as a mapping. The template's variables: declarations and default: work as on any other template, so domain above falls back to light, and a second dashboard can say domain: sensor to get a view per area with a sensor in it.

Views that repeat

A view in the page can repeat, exactly as one written on the dashboard strategy can: for_each over a written list, or for_each_from over entities, areas, devices, floors, labels, a Jinja template: or anything narrowed by category:. Each copy is given the source's values and its place, index, index0, count, first and last:

dashboard:
  views:
    - for_each_from:
        labels: true
      view:
        title: '[[label]]'
        cards:
          - type: markdown
            content: 'Label [[index]] of [[count]]'
    - for_each_from:
        template: "{{ ['light.kitchen', 'light.bedroom'] }}"
      view:
        title: '[[entity|friendly_name]]'
        cards:
          - type: tile
            entity: '[[entity]]'

A repeated view can carry a view strategy of its own, so a view per room can repeat a section per light in it. The inner strategy is written out the same as one on any other view; see Repeating Sections and Badges.

Keeping the page somewhere else

The page template can live on the strategy, as above, or on any dashboard the strategy borrows from: one named in decluttering_templates_from, or the library dashboard, which every dashboard borrows from without naming it. A second dashboard is then only this:

strategy:
  type: custom:decluttering-card-plus
  decluttering_templates_from: house-templates
  page:
    template: house_page
    variables:
      house: The Granary
      domain: sensor

The cards inside the page find their templates the same way, so entity_tile can live beside house_page on the lending dashboard.

The same request as decluttering_page

page: can also be written decluttering_page:. The two are read the same way and nothing else about the dashboard changes; the longer name matches the strategy's other decluttering_* keys. A second house, borrowing the hello_page above from a dashboard at the path house-templates:

strategy:
  type: custom:decluttering-card-plus
  decluttering_templates_from: house-templates
  decluttering_page:
    template: hello_page
    variables:
      house: The Granary

A dashboard with one view, Home, holding one card that says Hello from The Granary

Whichever name asked for the page, the dashboard it writes carries neither, so nothing asks for the page a second time. When both are given, page: is the one read.

What is filled in, and by what

The page's variables: fill every placeholder in the template's dashboard: body: the title, the views, the settings beside them, and what each repeat repeats over (the domain: '[[domain]]' above). What a repeated view holds is filled again for each copy, from that copy's values first and then the page's.

A custom:decluttering-card-plus card inside the page builds itself. The page fills in what the card is handed, its template:, its variables: and what it repeats over, and leaves the rest of its placeholders for the card's own template.

Placeholders the page leaves unset are reported in the browser console like any other. decluttering_templates, decluttering_defaults and the other decluttering_* keys inside the body are copied as written, not filled in, since they are definitions for the cards to use. The strategy's own decluttering_* keys are copied onto the dashboard too, and win over the template's when both set one.

When the page cannot be built

The dashboard is then one view, titled Page, with a card saying what is wrong:

The strategy has It says
views: of its own beside page: This dashboard has views of its own beside page: house_page. A page template builds the whole dashboard, so take the views out or the page.
a page: naming a template it cannot find The page names a template "nope" that is not in the strategy's decluttering_templates or on any dashboard it borrows from.
a page: naming a card, row or other template The page names "entity_tile", which does not build a dashboard. A page template has its content under dashboard:.

The page refuses rather than guess which views you meant. A card that names a page template is refused too:

"house_page" is a page template - it builds a whole dashboard under dashboard: - so no card can use it. Point a dashboard strategy's page: at it instead.

Editing it

Like any strategy dashboard, a page is edited as YAML in the raw configuration editor. The dashboard is written out again when the entity, device, area or floor registry changes, so a new area gets its view without a reload.

If Home Assistant offers to take control of the dashboard, saying yes swaps the page for the views it last wrote. They then stop following the registry and the template, and the page template is no longer used by that dashboard.


Next

→ Repeating Sections and Badges · Sharing Templates Between Dashboards · Defining Templates

Clone this wiki locally