-
Notifications
You must be signed in to change notification settings - Fork 1
Advanced Features
Power user features including templates, AI generation, and custom styling.
Magic Builder uses AI to generate button configurations from natural language descriptions.
- Click Magic button in the header ( icon)
- Enter your API key (Google AI Studio - free tier available)
- Describe what you want
- Click Generate
- Go to Google AI Studio
- Create a free account
- Generate an API key
- Paste into Magic Builder settings
- Key is stored locally in your browser
Effective prompts include:
- Entity type and purpose
- Desired visual style
- Color preferences
- Animation requirements
- State behavior
Examples:
"A glass-style light button with blue glow when on, gray when off, pulsing animation when active"
"Minimal temperature sensor card showing current temp with red/blue color based on value, no icon"
"Cyberpunk-style media player button with neon pink accents and animated border"
"Large square button for garage door with warning confirmation and 3D pressed effect"
- Complete button configuration
- Appropriate colors and styling
- State-based changes
- Animations (if requested)
- Layout optimization
- Cannot access your entities (use generic examples)
- Complex templates may need manual adjustment
- Very specific animations may not generate perfectly
- Works best with clear, specific descriptions
Templates enable dynamic content based on entity state.
Button Card uses JavaScript templates wrapped in:
[[[ // JavaScript code here return result; ]]]
| Variable | Description |
|---|---|
entity |
Current entity state object |
state |
Current state value (shorthand) |
user |
Current Home Assistant user |
variables |
Custom variables object |
states |
All Home Assistant states |
hass |
Full Home Assistant object |
javascript entity = { entity_id: "light.bedroom", state: "on", attributes: { brightness: 255, rgb_color: [255, 200, 100], friendly_name: "Bedroom Light", // ... more attributes }, last_changed: "2024-01-15T10:30:00Z", last_updated: "2024-01-15T10:30:05Z" }
yaml icon: | [[[ if (entity.state === 'on') return 'mdi:lightbulb'; return 'mdi:lightbulb-outline'; ]]]
yaml color: | [[[ const brightness = entity.attributes.brightness || 0; if (brightness > 200) return '#ffff00'; if (brightness > 100) return '#ffaa00'; return '#888888'; ]]]
yaml name: | [[[ if (entity.state === 'on') { return 'Light is ON'; } return 'Light is OFF'; ]]]
yaml state_display: | [[[ const temp = parseFloat(entity.state); if (temp > 30) return ' ' + temp + 'C'; if (temp < 10) return ' ' + temp + 'C'; return temp + 'C'; ]]]
yaml name: | [[[ const lights_on = Object.values(states) .filter(e => e.entity_id.startsWith('light.')) .filter(e => e.state === 'on') .length; return lights_on + ' lights on'; ]]]
- Navigate to Advanced Templates
- Enable template for the field you want
- Enter JavaScript template code
- Preview updates live
Check browser console:
- Template errors appear in console
- Use
console.log()inside templates for debugging
Common Issues:
- Missing return statement
- Undefined entity attributes
- Syntax errors in JavaScript
Define reusable values for templates.
yaml variables: my_color: '#ff5500' threshold: 50 alert_icon: 'mdi:alert'
Using in templates:
javascript if (entity.state > variables.threshold) { return variables.alert_icon; }
Variables can also be templates:
yaml variables: is_hot: | [[[ return parseFloat(entity.state) > 25; ]]]
- Variables are scoped to the button
- Cannot be shared between buttons (use HA helpers instead)
- Evaluated before other templates
Apply CSS directly to button elements.
| Target | Description |
|---|---|
card |
Main button container |
icon |
Icon element |
name |
Name text element |
state |
State text element |
label |
Label text element |
grid |
Grid container |
img_cell |
Entity picture container |
entity_picture |
Entity picture image |
Styles are CSS properties in YAML list format:
yaml styles: card: - background: linear-gradient(135deg, #667eea, #764ba2) - border-radius: 20px - box-shadow: 0 10px 20px rgba(0,0,0,0.3) icon: - color: white - filter: drop-shadow(0 0 5px white) name: - font-size: 16px - text-transform: uppercase
Common Card Styles: `yaml
- background-color: '#2c2c2c'
- background: linear-gradient(...)
- border: 1px solid #444
- border-radius: 12px
- box-shadow: 0 4px 6px rgba(0,0,0,0.3)
- backdrop-filter: blur(10px)
- transform: scale(1.05)
- transition: all 0.3s ease
- filter: brightness(1.2)
- opacity: 0.8 `
Common Text Styles: `yaml
- color: white
- font-size: 14px
- font-weight: bold
- text-transform: uppercase
- letter-spacing: 1px
- text-shadow: 0 2px 4px rgba(0,0,0,0.5) `
Common Icon Styles: `yaml
- color: '#f1c40f'
- width: 40px
- height: 40px
- filter: drop-shadow(0 0 8px currentColor)
- animation: spin 2s linear infinite `
Apply different styles based on state:
`yaml state:
-
value: 'on' styles: card: - background-color: '#f1c40f' icon: - color: black - animation: pulse 2s infinite
-
value: 'off' styles: card: - background-color: '#2c2c2c' icon: - color: '#666' - animation: none
-
value: 'unavailable' styles: card: - opacity: 0.3 - filter: grayscale(1) `
yaml styles: card: - transition: all 0.2s ease - '--hover-scale': 1.05 card:hover: - transform: scale(var(--hover-scale)) - box-shadow: 0 8px 16px rgba(0,0,0,0.4) card:active: - transform: scale(0.98)
Button Card exposes CSS variables:
| Variable | Description |
|---|---|
--button-card-icon-color |
Current icon color |
--button-card-background-color |
Background color |
--state-inactive-color |
HA inactive state color |
--state-active-color |
HA active state color |
Add additional content areas to buttons.
yaml custom_fields: notification: card: type: markdown content: "3 new messages"
yaml custom_fields: badge: card: type: markdown content: | <span style=" position: absolute; top: -5px; right: -5px; background: red; color: white; border-radius: 50%; width: 20px; height: 20px; font-size: 12px; display: flex; align-items: center; justify-content: center; ">!</span> styles: custom_fields: badge: - position: absolute - top: 0 - right: 0
yaml custom_fields: graph: card: type: custom:mini-graph-card entities: - sensor.temperature height: 50 show: labels: false points: false
- Design your button
- Click Copy YAML in header
- Full configuration copied to clipboard
- Click Import in header
- Paste button-card YAML
- Click Import
- Configuration loaded into editor
- Only imports button-card properties
- Complex templates may need adjustment
- Some advanced features require manual entry
Reduce shadow complexity: `yaml
- box-shadow: 0 0 5px #fff, 0 0 10px #fff, 0 0 20px #fff, 0 0 40px #fff
- box-shadow: 0 0 15px #fff `
Limit animations: `yaml
state:
- value: 'on' styles: icon: - animation: pulse 2s infinite
- value: 'off' styles: icon: - animation: none `
Use GPU-accelerated properties: `yaml
- transform: translateZ(0) # Force GPU layer
- will-change: transform # Hint for animation `
Cache expensive calculations:
javascript [[[ // Avoid recalculating every render const cachedValue = this._cachedValue || (this._cachedValue = expensiveCalculation()); return cachedValue; ]]]
Minimize states lookups: `javascript [[[ // Less efficient const a = states['sensor.temp'].state; const b = states['sensor.humidity'].state;
// More efficient - store reference const sensors = states; const a = sensors['sensor.temp'].state; const b = sensors['sensor.humidity'].state; ]]] `
- Configuration Options - Full settings reference
- Style Presets - Pre-built styles
- Troubleshooting - Common issues and solutions
Getting Started
Configuration
Advanced
Help