-
Notifications
You must be signed in to change notification settings - Fork 1
FAQ
Frequently asked questions about Button Builder.
Button Builder is a visual editor for creating Home Assistant dashboard card configurations. It includes three builders — for custom:button-card, custom:bubble-card, and HA's built-in Tile card — each available as its own sidebar panel. Instead of writing YAML by hand, you use a GUI to design cards and generate the configuration automatically.
The Button Card Builder generates YAML for custom:button-card, so you need button-card installed via HACS to use its output. Likewise, the Bubble Card Builder requires Bubble Card. The Tile Card Builder needs nothing extra — the Tile card is built into Home Assistant. You only need the card(s) whose builder you actually use.
Yes, Button Builder is free and open source under the MIT license.
Mostly yes. The main editor works without internet. The Magic Builder (AI) feature requires internet to connect to Google's AI API.
The easiest way is through HACS:
- Open HACS Integrations
- Search "Button Builder"
- Download and restart HA
See Installation for detailed instructions.
No, you can install manually by copying files to custom_components/button_builder/. However, HACS makes updates much easier.
You should see three entries: Button Card Builder, Bubble Card Builder, and Tile Card Builder.
After installation, you must restart Home Assistant. If it still doesn't appear, check:
- HA logs for errors
- Installation path is correct
- Browser cache is cleared
See Troubleshooting for more solutions.
- Open Button Builder from the sidebar
- Select an entity (optional)
- Apply a preset style
- Customize as needed
- Copy the YAML
- Paste into your dashboard
See Getting Started for a complete tutorial.
- Edit your dashboard
- Add a "Manual" card (or "Custom: Button Card")
- Paste the YAML from Button Builder
- Save
Yes! Click "Import" in Button Builder and paste your existing button-card YAML. It will load into the editor for modification.
Several reasons:
- Your dashboard theme affects colors
- Grid sizing differs from preview
- Entity attributes differ from preview simulation
See Troubleshooting#Preview Not Matching Dashboard.
Use the built-in Library: click Save, give your design a name (plus optional folder and tags), and it's stored in your browser. You can search, load, duplicate, and delete saved designs, and Export All downloads your whole library as a YAML backup. See Saving and Library.
Note that the library lives in browser storage — it doesn't sync between devices, so export backups for anything important.
Magic Builder is an AI-powered feature that generates button configurations from natural language descriptions. Describe what you want, and it creates the configuration.
Yes, Magic Builder uses Google's Gemini AI. You need a free API key from Google AI Studio. The key is kept in session storage only — it's cleared when you close the tab and is never sent anywhere except to Google's API.
Presets are pre-designed button styles. Apply a preset to instantly style your button, then customize further.
Yes! In the Button Card Builder, save any design as a custom preset — it appears in the preset panel under the Custom category. You can also save full designs to the Saving and Library.
Color Type determines what gets colored by state:
- icon - Only the icon changes color
- card - The entire card background changes
- label-card - Card and label change
- blank-card - Card only, icon stays white
Templates are JavaScript code that dynamically change button properties based on entity state. For example, changing the icon based on temperature value.
- Chrome/Chromium (recommended)
- Firefox
- Safari (some limitations)
- Edge
- HA Companion App
Yes. Both builders have a dedicated mobile layout with bottom-tab navigation (Preview / Configure / YAML), so editing on a phone is fully supported.
Button Builder requires Home Assistant 2024.1 or newer.
Yes, Button Builder works with both local and cloud HA installations.
Your current button configuration is stored in your browser's localStorage. It's not synced across devices or browsers.
Yes, but each device/browser has its own separate configuration. Copy YAML to transfer between devices.
No. Button Builder only generates YAML that you manually copy to your dashboard. It doesn't modify any Home Assistant files directly.
Yes! Contributions are welcome on GitHub:
- Bug reports and feature requests via Issues
- Code contributions via Pull Requests
- Documentation improvements
Most likely, state colors are overriding your background color. Clear the "State ON Color" and "State OFF Color" fields, or set Color Type to "blank-card".
- Ensure you're logged into Home Assistant
- Wait for entities to load (can take a few seconds)
- Try refreshing the page
- Check browser console for errors
Some browsers restrict clipboard access. Try:
- Manually select and copy the YAML text
- Use a different browser
- Ensure HTTPS (clipboard requires secure context)
Open an issue on GitHub with:
- Steps to reproduce
- Expected vs actual behavior
- Browser and HA version
- Screenshots if visual issue
Check GitHub Issues to see if it's already requested. If not, open a new feature request issue with your idea.
Yes! Preset suggestions are welcome. Open an issue with:
- Description of the style
- Example YAML if you have it
- Reference images
Magic Builder improvements depend on the AI model capabilities. Suggestions for better prompting or schema improvements are welcome.
- Getting Started - Begin using Button Builder
- Configuration Options - All available settings
- Troubleshooting - Solve common problems
Getting Started
Button Card Builder
Bubble Card Builder
Tile Card Builder
Workflow
Help