Skip to content

Getting Started

Jump to bottom
aspenrt78 edited this page Nov 29, 2025 · 2 revisions

Getting Started

This guide walks you through creating your first button with Button Builder.

Interface Overview

When you open Button Builder, you'll see a split-panel interface:

`

Button Builder [Import] [Copy YAML] [Presets]

Configuration Live Preview
Panel

Entity                                               
Appearance                  Button                   
Effects                     Preview                  
Actions                                              
Advanced                                
                                                        
                             YAML Output

`

Left Panel: Configuration

Drill-down navigation with categories:

  • Entity - Select entity, configure name/icon/state display
  • Appearance - Layout, colors, backgrounds, typography
  • Effects - Animations, shadows, borders, glass effects
  • Actions - Tap, hold, double-tap behaviors
  • Advanced - Templates, variables, extra styles

Right Panel: Preview

  • Live button preview - Updates in real-time
  • Size slider - Test different button sizes
  • ON/OFF toggle - Simulate entity states
  • Canvas settings - Background color/image
  • YAML output - Generated configuration

Quick Start: Your First Button

Step 1: Select an Entity

  1. Click into the Entity category
  2. Click on Core Settings
  3. Click the Entity ID dropdown
  4. Browse or search for your entity (e.g., light.living_room)
  5. Select it - the preview updates immediately

Step 2: Apply a Preset

  1. Click the Presets button in the header
  2. Browse the categories (try "Glass" or "Minimal")
  3. Click any preset to apply it
  4. The button preview updates with the new style

Step 3: Customize

Make it your own:

  1. Change the icon: Entity Core Settings Icon
  2. Adjust colors: Appearance Colors Card Background
  3. Resize: Appearance Layout Card Height or Aspect Ratio
  4. Add animation: Effects Animations Icon Animation

Step 4: Copy the YAML

  1. Click Copy YAML in the header
  2. The configuration is copied to your clipboard
  3. Paste it into your Home Assistant dashboard

Adding to Your Dashboard

Method 1: Visual Editor

  1. Edit your dashboard
  2. Click + Add Card
  3. Search for "Manual" or "Custom: Button Card"
  4. Paste the YAML from Button Builder
  5. Save

Method 2: YAML Mode

  1. Edit your dashboard in YAML mode
  2. Add a new card:

`yaml type: custom:button-card

Paste your Button Builder YAML here

entity: light.living_room name: Living Room icon: mdi:lightbulb

... rest of config

`

Understanding the Preview

State Simulation

The preview includes state simulation buttons:

  • ON - Shows how the button looks when entity is on
  • OFF - Shows how the button looks when entity is off

This helps you design state-based styling without toggling real devices.

Size Testing

Use the size slider to test your button at different sizes:

  • Buttons should look good from small (80px) to large (200px+)
  • Test aspect ratios that match your dashboard layout

Canvas Background

Click the **** icon to change the preview background:

  • Solid colors (dark, light, custom)
  • Your actual dashboard backgrounds (when running in HA)
  • Custom uploaded images

Working with Presets

Applying Presets

  1. Click Presets in the header
  2. Categories appear as tabs/list
  3. Click any preset to apply

Preset Tracking

When a preset is active:

  • The preset name shows: " Glassmorphism"
  • Settings from the preset are tracked
  • Modified settings show with edit indicator

State-Based Presets

Apply different presets for ON/OFF states:

  1. In the Presets panel, find Apply to State
  2. Choose: Always, ON State Only, OFF State Only
  3. Select different presets for each state

Resetting to Preset

If you've modified a preset and want to restore it:

  • Click the preset name in the header
  • Select "Reset to Preset Defaults"

Common Workflows

Creating a Light Button

  1. Select your light entity
  2. Apply "Minimal Dark" preset
  3. Enable Auto Color to match light color
  4. Set Icon Animation to "glow" when ON
  5. Copy YAML

Creating a Sensor Display

  1. Select your sensor entity
  2. Apply a minimal preset
  3. Disable Show Icon if not needed
  4. Enable Show State
  5. Add Units Override if needed
  6. Copy YAML

Creating a Script Button

  1. Select your script entity
  2. Apply any style preset
  3. Go to Actions Tap Action
  4. Set action to "toggle" or "call-service"
  5. Copy YAML

Creating an Area Card

  1. Select any entity (or leave blank)
  2. Apply an "Area Card" preset
  3. Set a custom Name for the area
  4. Choose an appropriate icon
  5. Set tap action to navigate to area view
  6. Copy YAML

Tips for Beginners

Start with Presets

Don't try to build from scratch. Apply a preset first, then customize.

Use Live Preview

The preview updates instantly - experiment freely!

Test Both States

Always check how your button looks in both ON and OFF states.

Copy Often

Copy your YAML frequently as you work. Browser refreshes can reset your config.

Check Mobile

Test your buttons at smaller sizes - they should be touch-friendly.

Next Steps

Navigation

Getting Started

Configuration

Advanced

Help

Clone this wiki locally