Configuration Options

Configuration Options

Complete reference for all Button Builder configuration options.

Entity Settings

Core Settings

Option	Type	Default	Description
Entity ID	string	-	Home Assistant entity ID (e.g., light.kitchen)
Name	string	Entity name	Display name for the button
Icon	string	Entity icon	MDI icon name (e.g., mdi:lightbulb)
Show Name	boolean	true	Display the name on the button
Show Icon	boolean	true	Display the icon on the button
Show State	boolean	false	Display the entity's current state
Show Entity Picture	boolean	false	Use entity picture instead of icon
Show Units	boolean	true	Display units with state (e.g., "22C")
Units Override	string	-	Custom unit string
Show Label	boolean	false	Display a custom label
Label	string	-	Custom label text (supports templates)

State Display

Option	Type	Default	Description
State Display	select	-	What to show as state: default, attribute, template
Attribute	string	-	Entity attribute to display (when State Display = attribute)
State Template	string	-	Jinja2 template for state (when State Display = template)

---

Appearance Settings

Layout

Option	Type	Default	Description
Layout	select	vertical	Button layout: vertical, horizontal, icon_name, name_icon, icon_state, etc.
Icon Position	select	top	Icon placement: top, bottom, left, right
Aspect Ratio	string	1/1	Card aspect ratio (e.g., 1/1, 16/9, 2/1)
Card Height	string	auto	Fixed height (e.g., 100px, 5rem)
Card Width	string	auto	Fixed width (overrides grid)

Layout Options Explained

Vertical (default)

  Icon
  Name
  State

Horizontal

Icon | Name | State

icon_name

Icon Name

name_icon

Name Icon

icon_state

Icon State

icon_name_state

Icon Name State

icon_name_state2nd

  Icon Name
    State

icon_label

Icon Label

Colors

Option	Type	Default	Description
Card Background	color	#2c2c2c	Main button background color
Icon Color	color	#ffffff	Default icon color
Name Color	color	#ffffff	Name text color
State Color	color	#aaaaaa	State text color
Label Color	color	#888888	Label text color

State Colors

Option	Type	Default	Description
State ON Color	color	#f1c40f	Icon/card color when entity is ON
State OFF Color	color	#4a4a4a	Icon/card color when entity is OFF
Color Type	select	icon	What to colorize: icon, card, label-card, blank-card
Auto Color	boolean	false	Use entity's color (e.g., light color)

Typography

Option	Type	Default	Description
Name Font Size	string	14px	Name text size
Name Font Weight	string	normal	Name text weight (normal, bold, 300-900)
State Font Size	string	12px	State text size
Label Font Size	string	11px	Label text size
Icon Size	string	24px	Icon dimensions

---

Effects Settings

Border & Radius

Option	Type	Default	Description
Border Radius	string	12px	Corner rounding (e.g., 8px, 1rem, 50%)
Border Width	string	0	Border thickness
Border Color	color	#444	Border color
Border Style	select	solid	Border style: solid, dashed, dotted, double

Shadows

Option	Type	Default	Description
Box Shadow	string	-	CSS box-shadow value
Shadow Presets	select	none	Quick shadow options: subtle, medium, strong, glow

Shadow Preset Values:

• subtle: 0 2px 4px rgba(0,0,0,0.2)
• medium: 0 4px 12px rgba(0,0,0,0.3)
• strong: 0 8px 24px rgba(0,0,0,0.4)
• glow: 0 0 20px rgba(255,255,255,0.3)

Glass Effects

Option	Type	Default	Description
Glass Effect	boolean	false	Enable glassmorphism effect
Blur Amount	string	10px	Backdrop blur intensity
Glass Opacity	number	0.2	Background opacity (0-1)
Glass Tint	color	#ffffff	Tint color for glass

Gradients

Option	Type	Default	Description
Enable Gradient	boolean	false	Use gradient background
Gradient Type	select	linear	Gradient type: linear, radial
Gradient Angle	number	135	Angle for linear gradients (0-360)
Gradient Start	color	#667eea	First color stop
Gradient End	color	#764ba2	Second color stop

Animations

Option	Type	Default	Description
Icon Animation	select	none	Icon animation when ON
State Animation	select	none	Animation when state changes
Hover Animation	boolean	true	Scale effect on hover

Animation Options:

• none - No animation
• spin - Continuous rotation
• pulse - Pulsing scale
• blink - Opacity blink
• bounce - Bouncing motion
• glow - Glowing effect
• rotating - Slower rotation
• shake - Shake side to side

---

Action Settings

Tap Action

Option	Type	Default	Description
Tap Action	select	toggle	Action on tap
Hold Action	select	more-info	Action on long press
Double Tap Action	select	none	Action on double tap

Action Types

Action	Description	Additional Options
toggle	Toggle entity state	-
more-info	Open entity dialog	-
call-service	Call HA service	Service, Service Data
navigate	Navigate to view	Navigation Path
url	Open URL	URL Path
assist	Open Assist dialog	-
fire-dom-event	Fire browser event	Event data
none	No action	-

Service Call Configuration

When using call-service:

Option	Type	Description
Service	string	Service to call (e.g., light.turn_on)
Service Data	object	Data to pass to service

Example Service Data:

service: light.turn_on
service_data:
  entity_id: light.bedroom
  brightness_pct: 75
  color_name: blue

Navigation Configuration

When using navigate:

Option	Type	Description
Navigation Path	string	Dashboard path (e.g., /lovelace/lights)

Confirmation

Option	Type	Default	Description
Confirmation	boolean	false	Require confirmation before action
Confirmation Text	string	"Are you sure?"	Custom confirmation message

---

Advanced Settings

Custom Styles (Extra Styles)

Option	Type	Description
Card Styles	CSS	Custom CSS for the card container
Icon Styles	CSS	Custom CSS for the icon
Name Styles	CSS	Custom CSS for the name
State Styles	CSS	Custom CSS for the state
Label Styles	CSS	Custom CSS for the label
Grid Styles	CSS	Custom CSS for the grid container
Image Styles	CSS	Custom CSS for entity picture

Example Custom Styles:

styles:
  card:
    - filter: saturate(0.5)
    - transition: all 0.3s ease
  icon:
    - animation: spin 2s linear infinite
  name:
    - text-transform: uppercase
    - letter-spacing: 2px

Templates

Option	Type	Description
Show	template	Conditional display (returns true/false)
Icon Template	template	Dynamic icon based on state
Name Template	template	Dynamic name based on state
Entity Template	template	Dynamic entity selection
Color Template	template	Dynamic color calculation

Template Variables:

• entity - Current entity state object
• state - Current state value
• user - Current HA user
• variables - Custom variables object
• states - All HA states

Example Templates:

icon: |
  [[[
    if (entity.state === 'on') return 'mdi:lightbulb';
    return 'mdi:lightbulb-outline';
  ]]]

color: |
  [[[
    if (entity.attributes.brightness > 200) return 'yellow';
    return 'white';
  ]]]

Custom Fields

Option	Type	Description
Custom Fields	object	Define additional content areas

Custom Fields Example:

custom_fields:
  temp:
    card:
      type: custom:mini-graph-card
      entities:
        - sensor.temperature

Variables

Option	Type	Description
Variables	object	Define reusable variables

Variables Example:

variables:
  threshold: 50
  warning_color: 'red'

color: |
  [[[
    if (entity.state > variables.threshold) return variables.warning_color;
    return 'green';
  ]]]

---

State-Based Overrides

Apply different settings based on entity state:

state:
  - value: 'on'
    styles:
      card:
        - background-color: '#f1c40f'
      icon:
        - color: black
  
  - value: 'off'
    styles:
      card:
        - background-color: '#2c2c2c'
      icon:
        - color: gray
  
  - value: 'unavailable'
    styles:
      card:
        - opacity: 0.5

State Matching Options

Match Type	Example	Description
Exact	value: 'on'	Match exact state
Operator	operator: '>'	Use comparison (>, <, >=, <=, !=)
Range	value: '50' operator: '>'	Match if state > 50
Regex	value: '/^Error/'	Regex pattern match
Default	value: 'default'	Catch-all fallback

---

Next Steps

• Getting Started - First steps with Button Builder
• Style Presets - Pre-built style configurations
• Advanced Features - Templates and Magic Builder