Deck Card

Deck Card

Deck Card groups normal Lovelace cards into a shared Orbit layout.

It can wrap cards into rows, show them as tabs, or place compact child cards over a main card.

type: custom:orbit-deck-card

Deck Card was added in Orbit Cards v0.14.0.

Layouts

Layout	Use for
wrap	Showing several child cards together in rows.
tabs	Switching between child cards in the same dashboard position.
overlay	Placing compact controls around a main child card.

Wrap Layout

Light theme	Dark theme

type: custom:orbit-deck-card
layout: wrap
items_per_row: 3
separate_cards: true
decks:
  - attributes: {}
    card:
      type: tile
      entity: light.kitchen_lights
  - attributes: {}
    card:
      type: tile
      entity: light.office_lights
  - attributes: {}
    card:
      type: tile
      entity: light.wetroom_lights

Wrap layout uses:

1. items_per_row to control how many child cards appear on each row.
2. separate_cards to choose between individual child card spacing or one grouped surface.
3. Per-item padding controls when a child card needs small spacing adjustments.
4. Native child visibility conditions to remove hidden items and reflow the remaining cards.

Use separate_cards: false when the child cards should feel like one joined group:

type: custom:orbit-deck-card
layout: wrap
items_per_row: 4
separate_cards: false
decks:
  - attributes: {}
    card:
      type: gauge
      entity: sensor.main_import_power
  - attributes: {}
    card:
      type: gauge
      entity: sensor.boiler_power

Tabs Layout

Home	Energy	Climate

type: custom:orbit-deck-card
layout: tabs
tab_font_size: 18px
decks:
  - attributes:
      icon: mdi:home
      name: Home
      default: true
    card:
      type: entities
      entities:
        - light.lounge
        - light.kitchen
  - attributes:
      icon: mdi:flash
      name: Energy
    card:
      type: history-graph
      entities:
        - sensor.main_import_power

Tabs layout uses:

1. attributes.name as the tab label.
2. attributes.icon as the tab icon.
3. attributes.default to choose the tab selected on page load.
4. tab_width_mode to control how tab widths are calculated. The default is equal.
5. tab_divider to show or hide the horizontal and vertical tab dividers. Dividers are shown by default.
6. Native child visibility conditions to hide both a child and its tab.

If more than one deck item is marked as default, the first default item wins.

Overlay Layout

Overlay layout uses the first deck item as the main card. Each remaining card or badge is positioned over it using precise pixel coordinates.

type: custom:orbit-deck-card
layout: overlay
decks:
  - attributes:
      force_padding: true
      padding_right: 80px
      padding_bottom: 80px
    card:
      type: entities
      entities:
        - light.lounge
        - light.kitchen
  - attributes:
      left: 260
      top: 16
      width: 48
      height: 48
      transparent_background: true
    badge:
      type: entity
      entity: light.lounge_lamp
  - attributes:
      left: 248
      top: 80
      width: 64
      fit: crop
      transparent_background: true
    card:
      type: button
      entity: scene.relax

Overlay layout uses:

1. The first deck item as the main card that determines the Deck Card size.
2. attributes.left and attributes.top to position each additional item from the main card's top-left corner.
3. attributes.width and attributes.height to resize or crop an item. Leave both unset to use the child card or badge's natural size.
4. attributes.fit to choose resize or crop. Resize is the default and scales the child; crop keeps its original scale and clips it to the configured dimensions.
5. attributes.transparent_background to remove the child card surface, border, and shadow when a control should blend into the main card.
6. The main item's padding controls when space should be reserved inside the main card for overlaid controls.

Overlay children are contained inside the main card area. The visual editor labels the first item as Main and shows position, size, fit, and background controls only for additional overlay items.

Overlay Cards And Badges

Additional overlay items can be normal Lovelace cards or native Home Assistant badges. Select Cards or Badges above the child picker in the visual editor.

type: custom:orbit-deck-card
layout: overlay
decks:
  - attributes: {}
    card:
      type: picture-entity
      entity: camera.front_door
  - attributes:
      left: 12
      top: 12
      transparent_background: true
    badge:
      type: entity
      entity: binary_sensor.front_door

Tab Width Modes

Mode	Behaviour
equal	All tabs share the available width equally. This is the default.
dynamic	Tabs size to their content and can scroll when needed.
custom	Each tab can use its own attributes.width.

Example with a custom tab width:

type: custom:orbit-deck-card
layout: tabs
tab_width_mode: custom
decks:
  - attributes:
      icon: mdi:sofa
      name: Lounge
      width: 140px
    card:
      type: tile
      entity: light.lounge_lights

Tabbed Card Compatibility

Deck Card is compatible with the same basic item shape used by custom:tabbed-card.

For a simple tabbed-card config, change:

type: custom:tabbed-card
tabs:
  - attributes:
      icon: mdi:home
      label: Home
    card:
      type: entities
      entities:
        - light.lounge

to:

type: custom:orbit-deck-card
layout: tabs
decks:
  - attributes:
      icon: mdi:home
      label: Home
    card:
      type: entities
      entities:
        - light.lounge

Deck Card accepts attributes.label from tabbed-card configs. When the visual editor opens the card, it saves that value back as attributes.name.

Deck Items

Every entry in decks contains attributes and either a card or a badge:

decks:
  - attributes:
      icon: mdi:home
      name: Home
    card:
      type: entities
      entities:
        - light.lounge

Key	Description
attributes	Deck item metadata used by tabs and the editor.
card	The child Lovelace card config.
badge	The child Home Assistant badge config. Use instead of card.

attributes is owned by Deck Card. The card or badge config is passed to Home Assistant as a normal child element.

Attributes

Attribute	Description
name	Tab label.
label	Tab label accepted from tabbed-card configs. The editor saves it as name.
icon	Tab icon.
default	Selects this tab on page load. Only one tab should be default.
left	Overlay child horizontal position in pixels from the main card's left edge. Defaults to 0.
top	Overlay child vertical position in pixels from the main card's top edge. Defaults to 0.
width	Per-tab width in custom tab mode, or optional overlay item width. Overlay items use their natural width when unset.
height	Optional overlay item height. Overlay items use their natural height when unset.
fit	Overlay fit mode: resize or crop. Defaults to resize.
transparent_background	Controls the child surface, border, and shadow in Wrap, Tabs, and secondary Overlay items.
tap_action	Optional tap action override for this deck item.
hold_action	Optional hold action override for this deck item.
double_tap_action	Optional double tap action override for this deck item.
force_padding	Forces Deck Card padding values to override child-card padding support.
padding_top	Optional top padding for this child card.
padding_bottom	Optional bottom padding for this child card.
padding_left	Optional left padding for this child card.
padding_right	Optional right padding for this child card.

Child Cards And Badges

Deck Card can contain Home Assistant cards, custom cards, and native badges.

type: custom:orbit-deck-card
layout: wrap
decks:
  - attributes:
      name: Temperature
    card:
      type: thermostat
      entity: climate.lounge
  - attributes:
      name: Graph
    card:
      type: history-graph
      entities:
        - sensor.lounge_temperature

Use the Cards and Badges tabs in the child picker to choose the element type. If the child exposes a visual editor, Deck Card uses that editor. If not, Home Assistant falls back to YAML editing for that child.

Cards that already have their own layout controls should usually keep those controls inside the child card. Use Deck Card padding only when you need the deck item itself to add spacing around the child.

Child Visibility

Wrap and Tabs layouts honour Home Assistant visibility conditions stored inside each child card or badge config:

type: custom:orbit-deck-card
layout: tabs
decks:
  - attributes:
      name: Energy
      icon: mdi:flash
    card:
      type: entities
      entities:
        - sensor.main_import_power
      visibility:
        - condition: state
          entity: input_boolean.show_energy
          state: "on"
  - attributes:
      name: Home
      icon: mdi:home
    card:
      type: entities
      entities:
        - light.lounge

When a Wrap child becomes hidden, the visible children reflow into the available columns. When a Tabs child becomes hidden, its tab is removed; if it was selected, Deck Card falls back to the first visible tab. Hidden children continue observing their conditions so they can reappear without rebuilding the dashboard.

Overlay layout does not apply child visibility conditions because overlay positioning depends on a fixed item list.

Interactions

Deck Card can override child card tap, hold, and double tap actions per deck item.

When no Deck Card interaction is configured, the child card keeps its own default action behaviour.

Deck Card interaction overrides are stored under the deck item's attributes.

type: custom:orbit-deck-card
layout: wrap
decks:
  - attributes:
      name: Energy
      tap_action:
        action: navigate
        navigation_path: /dashboard-energy
      hold_action:
        action: more-info
    card:
      type: custom:gauge-card-pro
      entity: sensor.main_import_power

Child card actions can still exist inside card when they belong to the child card itself:

decks:
  - attributes:
      name: Light
    card:
      type: tile
      entity: light.lounge
      tap_action:
        action: toggle

Priority:

1. Deck Card uses the interaction configured in attributes when it exists.
2. If no Deck Card interaction is configured, the child card keeps its own configured/default action.

This means you can leave Deck Card interactions unset for normal child-card behaviour, then override only the specific deck items that need different tap, hold, or double tap actions.

The Deck Card visual editor lists only these deck-level overrides. The child card's own defaults and configured interactions remain in its child editor.

Styling

Deck Card supports shared styling for tabs and per-item styling for child surfaces and spacing.

type: custom:orbit-deck-card
layout: tabs
tab_color: primary-text-color
tab_active_color: primary-color
tab_background_color: card-background-color
tab_font_size: 18px
decks:
  - attributes:
      name: Home
    card:
      type: entities
      entities:
        - light.lounge

Per-item padding can be useful when a child card needs small layout correction:

decks:
  - attributes:
      force_padding: true
      padding_top: 5px
      padding_bottom: 0px
      padding_left: 0px
      padding_right: 0px
    card:
      type: custom:gauge-card-pro
      entity: sensor.main_import_power

Padding values are stored on each deck item's attributes.

force_padding: true is useful when a child card exposes its own padding support and Deck Card should override it. When force_padding is not enabled, child cards with their own padding support can keep control of their internal spacing.

Use attributes.transparent_background to control whether Deck Card removes a child's own surface, border, and shadow:

decks:
  - attributes:
      transparent_background: false
    card:
      type: tile
      entity: light.lounge

The editor defaults this to enabled for Tabs and joined Wrap layouts (separate_cards: false), and disabled for separate Wrap cards and secondary Overlay items. An explicit true or false overrides that layout default.

Options

Option	Description
layout	wrap, tabs, or overlay. Defaults to wrap.
decks	List of deck items. Each item contains attributes and either card or badge.
items_per_row	Wrap layout only. Number of child cards per row. Defaults to 1.
separate_cards	Wrap layout only. Adds spacing and individual child card surfaces.
tab_width_mode	Tabs layout only. equal, dynamic, or custom. Defaults to equal.
tab_font_size	Tabs layout only. CSS font size for tab labels.
tab_divider	Tabs layout only. Shows horizontal and vertical dividers. Defaults to true; set to false to hide them.
tab_color	Tabs layout only. Inactive colour.
tab_active_color	Tabs layout only. Active colour and underline colour.
tab_background_color	Tabs layout only. Background colour.
attributes.left	Overlay layout only. Horizontal position in pixels. Defaults to 0.
attributes.top	Overlay layout only. Vertical position in pixels. Defaults to 0.
attributes.width	Custom tab width or overlay item width.
attributes.height	Overlay item height.
attributes.fit	Overlay layout only. resize or crop. Defaults to resize.
attributes.transparent_background	Wrap, Tabs, and secondary Overlay items. Overrides the layout default for the child surface, border, and shadow.
attributes.tap_action	Optional per-item tap action override.
attributes.hold_action	Optional per-item hold action override.
attributes.double_tap_action	Optional per-item double tap action override.
attributes.force_padding	Forces Deck Card padding to override child-card padding support.
attributes.padding_top	Optional per-item top padding.
attributes.padding_bottom	Optional per-item bottom padding.
attributes.padding_left	Optional per-item left padding.
attributes.padding_right	Optional per-item right padding.

Visual Editor

The Deck Card editor includes:

• Setup tab for choosing Wrap, Tabs, or Overlay and configuring layout-wide options.
• Card tab for deck item order, tab details, overlay position/size/fit, child card or badge editing, item styling, and interactions.
• Add, duplicate, delete, move left, and move right controls for deck items.
• Native card and badge pickers and child editors where Home Assistant exposes them.
• The selected child's registered card/badge name in the Card tab heading.
• A transparent-background switch in supported layouts.

The live preview follows and outlines the selected deck item while editing; the thin selection marker is editor-only and never appears on the dashboard. In Wrap layout, a selected child that normally needs more width temporarily expands in the editor preview so its editor and content are not squeezed into the deck column. The Cards/Badges type tabs are shown while choosing a child and hidden after a type has been selected.