Subpage

A Subpage card works like a folder. Tapping it on the panel opens a new page with its own set of cards. This is useful for grouping related controls together, such as all the lights in one room, without filling up the home screen.

A subpage has one fewer usable slot than the home screen because it includes a Back card. Subpage cards on the home screen can show a small chevron marker so you can spot them easily. You can turn this marker on or off with Screen: Subpage Chevron in the Clock Bar settings.

Setting Up a Subpage

1. Select a card on the home screen and change its type to Subpage.
2. Choose a subpage Type. Generic is a normal folder, while Lights, Climate, Presence, and Media use useful defaults for those common room pages.
3. Set a Label and Icon if you want them.
4. Click Edit Subpage in the card settings, or right-click the card and choose Edit Subpage.
5. The preview switches to the subpage. Add and arrange cards here the same way you would on the home screen.
6. Click the Back card to return to the home screen.

You can also right-click an empty space on the home screen and choose Create Subpage.

Subpages can contain Switch, Lights, Action, Trigger, Sensor, Doors & Windows, Presence, Slider, Cover, Garage Door, Lock, Date & Time, Clock, World Clock, Weather, Media, Climate, and Internal Switches cards. Subpages cannot contain another Subpage card.

Open a Page From Home Assistant

You can ask Home Assistant to wake the panel and open a page directly. This is useful in automations, scripts, dashboards, or voice routines where you want the panel to jump to a relevant page.

This Home-Assistant-to-panel action is disabled on the ESP32-S3 4-inch panel because it can stop Home Assistant completing the panel startup registration on that lower-memory model. Tapping Subpage cards on the panel still works normally.

Use the ESPHome action named after your device:

action: esphome.<device_name>_navigate
data:
  target: "Lights"

Replace <device_name> with the ESPHome device name shown in Home Assistant. For example, if the device is called hall_panel, the action is:

action: esphome.hall_panel_navigate
data:
  target: "Lights"

Test It in Home Assistant

Before using the action in an automation or dashboard button, test it from Home Assistant:

1. Go to Developer Tools.
2. Open the Actions tab.
3. Search for navigate or your panel name, such as hall_panel.
4. Select the ESPHome action for your panel.
5. Enter the target page and click Perform action.

For example:

action: esphome.hall_panel_navigate
data:
  target: "Lights"

To return to the home screen, use:

action: esphome.hall_panel_navigate
data:
  target: "home"

The action is not an entity, so it will not appear in the entity list. It only appears in Developer Tools > Actions after the panel firmware has registered it with Home Assistant. If Home Assistant shows Action not found or Unknown action selected, update the panel firmware and reload or restart the ESPHome integration.

The target value can be:

• home or main to open the home screen.
• The Label you set on a Subpage card, such as Lights, Heating, or Media. Matching is not case-sensitive, so lights and Lights work the same way.
• slot:3 to open the subpage attached to home screen slot 3. This is mainly a fallback for troubleshooting; using the subpage label is easier.

You do not need to know a page number. Use the same label you gave the Subpage card on the home screen.

If two subpages use the same label, the first matching home screen slot opens. To avoid surprises, give each subpage a unique label. If Home Assistant sends a label or slot that does not exist, the panel logs a warning and stays on the current page.

The panel wakes before navigating, so the action works when the screen is off, dimmed, or showing the clock screensaver. It does not change long-press behavior. If you use the Home screen timeout, the panel will still return to the home screen using that normal setting.

Show State

Turn on Show State if you want the Subpage card on the home screen to show state.

Subpage cards can show state in three ways:

• Icon uses the card's Icon as the off icon and shows an On Icon when active. Enter a State Entity to track a specific Home Assistant entity, or leave it blank to keep the existing automatic behavior where the Subpage card lights up if any active-capable card inside it is on, open, playing, unlocked, or otherwise active.
• Numeric shows a Home Assistant sensor value in the large number style used by Sensor cards. Choose a Sensor Entity, Unit, and Unit Precision.
• Text shows a Home Assistant sensor state where the card label normally appears. Choose a Sensor Entity.

Read-only cards such as Sensor, Date, Clock, World Clock, and Weather do not affect Icon mode. Numeric and Text modes use the sensor entity you enter on the Subpage card. They do not automatically count the cards inside the subpage; use a Home Assistant helper or template sensor for that.

Moving Cards Between Pages

You can cut, copy, and paste cards between the home screen and subpages. Right-click a card, choose Cut or Copy, then right-click an empty space on the destination page and choose Paste.