🖼️ Material Options Card

NOTE

✨ Available on 💎 Pro & Ultimate Version Only

🌟 Overview

The Material Options Card (material-options-card) is a versatile Lovelace card designed to create navigation buttons, menus, or entity controls with a clean, modern style inspired by Material 3 (M3) Expressive. It is perfect for building settings pages, quick links, multi-room navigators, or elegant entity toggles.

☀️ Light Mode

🌙 Dark Mode

🔧 Dynamic Mode On

☀️ Light Mode

🌙 Dark Mode

✨ Features

• 🎨 Adaptive Card Modes: Choose between standard options layout or dynamic styling (which lights up when the bound entity is ON).
• 🔄 Conditional Dual Icons: Automatically render distinct icons depending on whether the entity is on or off.
• 📐 Customizable Geometry: Pre-set corner styles (small, medium, large) or full arbitrary CSS border radius (28px, 50px).
• ↔️ Inline Text Flow: Toggle display_text_inline to show title and subtitle side-by-side with automatic text truncation.
• 📊 Trailing State & Interactive Controls: Display interactive Material 3 Expressive controls (custom dropdown selector, switch toggle, button press, or formatted state pill badge) directly on the right edge with include_entity_options.
• 🪄 Dynamic Templating: Full JavaScript templating support ([[[ return ... ]]]) for title, subtitle, and icons.
• 🚨 Dynamic Alert & Hazard Colors: Automatically highlights the option card, trailing controls, and state badges with Material 3 error tokens when an entity reports an active hazard, problem, low battery (<= 15%), or triggered alarm.
• 👆 Interactive Actions: Complete support for single tap, long press (hold_action), and double tap (double_tap_action).

🖥️ Visual Editor Preview

When adding a new material-options-card via the Home Assistant visual Lovelace editor, a pre-filled preview is displayed:

• Name: "Material Options"
• Subtitle (label): "Subtitle"
• Icon: ⚙️ (mdi:cog)

TIP

Smart Field Reset: These default placeholder values are displayed only for live UI visual preview. As soon as you configure a property in the visual editor (such as picking an entity or typing a custom title), the placeholder values are automatically removed, leaving a clean configuration to customize.

🛠️ Configuration Options

Below is the complete list of options available to customize the material-options-card.

Option	Type	Description	Default	Required
type	string	Must be custom:material-options-card.	-	✅ Yes
name	string	📝 The main title displayed on the card. Supports JavaScript templating.	-	❌ No
label	string	📜 Secondary subtitle text displayed below the name. Supports JavaScript templating.	-	❌ No
entity	string	🔗 The entity ID to associate with the card. Enables state-based features (dynamic icons, state pills).	-	❌ No
options_type	string	🎨 Card style. Options: options (standard) or dynamic (active accent background when entity is ON).	options	❌ No
icon	string	🖼️ The icon to display. If omitted and an entity is provided, the entity's icon is used. Supports templates.	-	❌ No
dual_icon	boolean	🔄 Enables different icons for on and off states. Requires entity.	false	❌ No
icon_on	string	💡 Icon to show when the entity is on. Requires dual_icon: true.	-	❌ No
icon_off	string	🌑 Icon to show when the entity is off. Requires dual_icon: true.	-	❌ No
border_radius_style	string	📐 Border radius preset. Options: small, medium, large, custom.	small	❌ No
border_radius	string	📏 Custom CSS border radius value (e.g., 28px). Requires border_radius_style: custom.	-	❌ No
use_large_buttons	boolean	🐘 Increases padding for a larger, more spacious touch target.	false	❌ No
display_text_inline	boolean	↔️ Displays both the title and subtitle alongside each other on a single line, even if long, without wrapping.	false	❌ No
include_entity_options	boolean	📊 Displays interactive M3 control (dropdown for select, switch, button, automation run, or state pill badge) on right edge.	false	❌ No
show_entity_state	boolean	🎛️ Alias for include_entity_options to toggle the trailing entity state or control.	false	❌ No
entity_options	string	⚡ Automation display mode when entity is an automation. Options: states (show status badge) or run (show interactive trigger button).	states	❌ No
tap_action	object	👆 Custom action for a single tap (e.g., toggle, more-info, navigate, call-service).	-	❌ No
hold_action	object	👆🏼 Custom action for a long press.	-	❌ No
double_tap_action	object	✌️ Custom action for a double tap.	-	❌ No

🪄 Dynamic Templating

The card supports JavaScript template expressions evaluated in real-time via evaluateTemplateEngine:

• Enclose your expression between [[[ ... ]]].
• Access states using states['<entity_id>'].state and attributes via states['<entity_id>'].attributes.<attribute>.
• Templating can be applied to name, label, and icon.

label: "[[[ return states['sensor.power_consumption'].state + ' W currently used' ]]]"

TIP

For a comprehensive guide, ready-to-use code snippets, and structured examples on how to make the most of both engines, check out our Template Configurations Documentation.

🚀 Usage Examples

1. Simple Navigation Card

Creates a clean navigation button pointing to another Lovelace dashboard view.

type: custom:material-options-card
name: Lights
label: Go to lighting controls
icon: mdi:lightbulb-group
tap_action:
  action: navigate
  navigation_path: /lovelace/lights

2. Entity Control (Dynamic Mode Switch)

Controls a smart switch. The card background dynamically lights up when active, and tapping toggles the device.

type: custom:material-options-card
entity: switch.desk_socket
name: Desk Socket
options_type: dynamic
include_entity_options: true
tap_action:
  action: toggle
hold_action:
  action: more-info

3. Dual Icons for Window / Door Sensors

Shows distinct icons for open and closed states alongside the sensor state.

type: custom:material-options-card
entity: binary_sensor.living_room_window
name: Living Room Window
dual_icon: true
icon_on: mdi:window-open-variant
icon_off: mdi:window-closed-variant
include_entity_options: true

4. Inline Text with Custom Pill Geometry

A modern pill-shaped button with title and subtitle displayed inline on a single line.

type: custom:material-options-card
name: Relax Scene
label: Evening ambiance
icon: mdi:palette-outline
display_text_inline: true
use_large_buttons: true
border_radius_style: custom
border_radius: 28px
tap_action:
  action: call-service
  service: scene.turn_on
  target:
    entity_id: scene.relax

5. Automation Trigger Button

Allows triggering an automation manually with an interactive M3 button (complete with loading spinner and completion feedback).

type: custom:material-options-card
entity: automation.good_night_routine
name: Good Night
label: Run shutdown sequence
icon: mdi:weather-night
include_entity_options: true
entity_options: run
tap_action:
  action: more-info

🎨 Extended Customization

⚠️ LICENSE

The Material Options Card is an exclusive component for 💎 Pro & Ultimate supporters. Obtain your official license and unlock the complete Material Home Assistant suite on materialhomeassistant.com 🚀.

This card includes native support for Card-Mod, allowing you to inject custom CSS styles, animations, or token overrides directly.

💡 ADVANCED STYLING

👉 Check out the Styling & Card-Mod Guide.