Configuration

Configuration

All options live on the top-level card config (type: custom:tabdeck-card) except per-tab options, which live on each entry of tabs.

Top-level options

Option	Type	Default	Description
tabs	list	required*	The tabs to show. See Per-tab options. *Optional when auto_tabs is set.
auto_tabs	map	—	Generate a tab per item from a Jinja list (template + optional tab_template), or per area/label (source: areas | labels, domains, exclude). See Dynamic tabs.
default_tab	number | string	0	Tab shown first. A number is a 0-based index; a string matches a tab name.
preset	default | ios | material | glass | minimal | rail	—	A bundle of styling options; explicit keys override it. See Style presets.
position	top | bottom | left | right	top	Where the tab bar sits relative to the content.
style	underline | pill | segmented | boxed | text	underline	Visual style of the tab bar. See Extra bar styles.
tab_display	both | icon | label	both	Show icons, labels, or both. See Tab display mode.
tab_display_narrow / narrow_width	both | icon | label / px	— / 450	Display mode when the card is narrower than narrow_width. See Responsive layouts.
split	number | {min_width, columns}	—	At or above this card width, show all tabs side by side (no bar). See Responsive layouts.
align	start | center | end | justify	start	How tabs are distributed along the bar. See Tab alignment.
badge_display	text | dot	text	Render badges as text or a dot. See Badge display mode.
badge_format	{precision, unit, max}	—	Default numeric badge formatting for every tab. See Badges.
transition	none | fade | slide	none	Animate content on tab switch. See Panel transitions.
indicator_size	number (1–16)	3	Underline indicator thickness in px. See Indicator thickness.
accent_indicator	boolean	true	Colour the indicator by the selected tab's accent. See Accent indicator.
scrollable	auto | true | false	auto	Whether the bar scrolls horizontally when tabs overflow. auto scrolls only when needed.
sticky	boolean	false	Pin the bar while content scrolls. See Sticky tab bar.
collapsible / start_collapsed	boolean	false	Tap the active tab to fold the content away / start folded. See Collapsible deck.
scroll_spy	boolean	false	Stack all tabs as sections; the bar scrolls to and tracks them. See Scroll-spy.
scroll_buttons / overflow_menu	boolean	false	Scroll arrows / ⋯ jump-menu when the bar overflows. See Scroll buttons.
swipe_mouse	boolean	false	Change tabs by mouse drag (desktop).
unmount_hidden	boolean	false	Keep only the active tab's card mounted. See Performance.
header	boolean	false	Show the active tab's title above the content. See Content header.
transition	none | fade | slide	none	Panel switch animation. See Panel transitions.
aria_label	string	Tabs	Accessible name for the tab bar (screen readers).
remember	none | browser | url | entity	none	How the selected tab is remembered. See Navigation & Persistence.
lazy	boolean	false	When true, a tab's card is only built the first time it becomes visible.
animated	boolean	true	Animate the selection indicator as it moves between tabs.
swipe	boolean	false	Allow left/right swipe gestures to change tabs (mobile).
auto_rotate	number | {interval, resume_after}	—	Cycle tabs every N seconds; pauses after interaction. See Auto-rotate & idle return.
idle_return	number (seconds)	—	Return to the default tab after inactivity. See Auto-rotate & idle return.
styles	map	—	CSS variables/properties applied to the card. See Theming.

Legacy: options.defaultTabIndex is still accepted as a fallback for default_tab.

Per-tab options

Each item in tabs:

Option	Type	Default	Description
card	card config	required*	Any Lovelace card configuration. (*Not needed for a tap_action tab.)
cards	list of card configs	—	Multiple cards, auto-stacked. See Multiple cards per tab. *Either card or cards.
name	string	—	Tab label. Falls back to Tab N when omitted.
subtitle	string	—	Secondary text under the label. See Tab subtitles.
icon	string (mdi)	—	Tab icon, e.g. mdi:lightbulb.
accent	string (CSS colour)	—	Accent colour for the tab (indicator + selected state).
color	string (CSS colour)	—	Fixed label/icon colour for the tab. See Per-tab colour.
badge	string	—	An entity id (shows its state) or a Jinja template. See Badges.
badge_format	{precision, unit, max}	—	Numeric badge formatting (overrides the top-level default). See Badges.
disabled	boolean	false	Show the tab greyed-out and non-selectable. See Disabled tabs.
card_size	number	—	getCardSize() hint (rows) for this tab, so masonry sizing is stable across tab switches.
tap_action	action	—	Tap runs this action instead of opening the tab (navigation tabs; no card needed). See Navigation & action tabs.
enter_action / leave_action	action	—	HA action when the tab becomes / stops being active. See Tab-change actions.
hold_action / badge_action	action	—	HA action on tab long-press / badge click. See Tab & badge actions.
visibility	list of conditions	—	Conditions for showing the tab (supports and/or/not). See Tab Visibility.
styles	map	—	CSS properties applied to the card while this tab is active (over the top-level styles). See Theming.
alert	list of conditions	—	While all are met, the tab pulses in the alert colour. See Alert pulse.

name, subtitle, icon, accent and color also accept a Jinja template that renders live. See State-driven icons, names & colours.

Full example

type: custom:tabdeck-card
position: top
style: pill
default_tab: Climate
remember: url
animated: true
swipe: true
lazy: true
tabs:
  - name: Climate
    icon: mdi:thermostat
    accent: "#e8743b"
    card:
      type: thermostat
      entity: climate.living_room

  - name: Cameras
    icon: mdi:cctv
    badge: binary_sensor.motion_any   # shows on/off
    card:
      type: picture-glance
      entities: []
      camera_image: camera.driveway

  - name: Guests
    icon: mdi:account-group
    visibility:
      - condition: state
        entity: input_boolean.guest_mode
        state: "on"
    card:
      type: entities
      entities:
        - input_boolean.guest_wifi

See also

• The Visual Editor — set all of the above without YAML.
• Features — index of every optional feature and its config key.