ha-dashboard-studio/dashboard_studio/DOCS.md

# Dashboard Studio

A drag-and-drop dashboard builder that lives in its own sidebar tab.

## Using it

1. Open **Dashboard Studio** in the Home Assistant sidebar.
2. Press **Edit**. Pick widgets from the left panel, drag them anywhere on the grid, and resize from the bottom-right corner. Other widgets move out of the way.
3. Set up the selected widget in the right panel: entity, labels, icon, thresholds, colors.
4. With nothing selected, the right panel holds dashboard settings: theme, tile style, colors, background image, grid and kiosk options.
5. Press **Done**. Changes save automatically.

Keyboard shortcuts in edit mode: arrow keys move, Shift+arrows resize, ⌘D or Ctrl+D duplicates, Delete removes, ⌘Z or Ctrl+Z undoes, and ⇧⌘Z or Ctrl+Shift+Z redoes.

More editing tools:

- **Search** at the top of the widget list finds a widget by name. Press Enter to add the first match.
- **Entity fields** open a list of your entities with their icon, name, ID and current state. Type to filter by name or ID, use the arrow keys and Enter, or click one.
- **Several widgets at once:** Shift-click or ⌘-click (Ctrl-click) widgets to select them together. Drag one to move them all, or use the arrow keys. The right panel can line up their left, right, top or bottom edges, give them the same width or height (that of the widget you clicked last), duplicate them, copy them elsewhere or delete them.
- **Copy to…** (in the right panel) copies the selected widgets to another tab or another dashboard.
- **Into a scroll or swipe card:** drag a widget onto a horizontal scroll or swipe card; it lights up, and when you let go the widget becomes one of its cards. To take a card out again, open it in the container's settings and choose **Take out of this card**.

## Look and feel

- **Theme:** *System* follows your device's light or dark appearance. The other 14 themes are fixed: Light, Dark, Nord, Dusk, Forest, Graphite, Indigo, Rose, Ocean, Sunrise, Lavender, Mint, Sand, and High contrast for maximum readability. Text meets accessibility contrast levels in every theme. Changing any color switches the theme to *Custom*.
- **Tile style:** *Cards* puts every widget on a tile. *Outlined* draws a thin border instead. *Plain* removes the cards completely, so widgets sit straight on the background. You can also turn off the background for a single widget under **Style → No background**.
- **Lights that are on** glow: the tile turns warm, or takes on the bulb's color for color lights. In Plain style, the light's icon and brightness bar glow instead.
- **Icons:** widgets pick an icon automatically. To change one, click the icon next to the field to open the icon picker (over 130 icons for rooms, appliances, tools and devices, searchable in English and Dutch), type an icon name, or paste an emoji.

## Widgets

Heading, entity tile, big value (with warning and critical levels), gauge, light (on/off and brightness), thermostat, history graph (several sensors), clock, weather, entity list, button (runs any Home Assistant action with JSON data), media player, **car**, **calendar**, camera, text (with `{{ sensor.x }}` live values), **photos** and web page.

### Photos and Immich

The Photos widget shows one picture or a slideshow that fades between photos. Tap it to skip to the next photo. Pick a source:

- **Links:** paste one or more image URLs, one per line.
- **Immich:** tick one or more albums. Both your own albums and albums shared with you appear.

To use Immich, open this app's **Configuration** tab in Home Assistant. Enter your Immich URL (for example `http://192.168.1.20:2283`) and an API key, which you create in Immich under **Account Settings → API Keys**. Restart the app afterwards. The key stays on the server: browsers only receive the photos, never the key. You can also set how often the photo changes, shuffle the order, and show the date each photo was taken.

### Calendar

Add one or more `calendar.` entities to see an agenda of the coming days, grouped under Today, Tomorrow and then dates. Each calendar gets its own color bar. When you show several calendars, each event is also labelled with its calendar's name, so the color isn't the only clue. An event that is happening right now is marked **Now**. It works with every calendar integration in Home Assistant, such as Google, CalDAV and local calendars. Events refresh every few minutes.

### Waste collection (Afvalwijzer)

This card works with the [Afvalwijzer](https://github.com/xirixiz/homeassistant-afvalwijzer) integration. Once that integration is set up for your address, the card finds its waste sensors by itself, so there's nothing to configure. To show only some types, pick the sensors under **Waste sensors**.

- **Next** layout: the coming pickup large, with every waste type collected that day as a colored bin. When the pickup is tomorrow, it adds a reminder to put the bin out tonight. Later pickups follow in a list.
- **List** layout: every pickup as a row with its type, "Tomorrow" or "In 6 days", and the date.

Bins use the integration's own colors (GFT green, Papier blue, PMD maroon, and so on), and each bin is always named, so the color is never the only clue. Types with no pickup planned are hidden. You can limit the card to a number of pickups, or to pickups within a number of days.

### Clock with weather

Pick a weather entity in the clock's settings to show the current conditions and temperature under the time. Today's high and low come from Home Assistant's forecast, refreshed every half hour. Tap the weather to see all its details.

- **Text position:** place the time anywhere in the card with the 3×3 grid: top left, top, top right, left, center, right, bottom left, bottom or bottom right.
- **Background image:** choose image links (one per line) or Immich albums. With more than one photo the clock fades between them; set how often. Tap the clock to skip to the next photo right away. **Darken the image** keeps the time readable on bright photos (30% by default), and the text turns white with a soft shadow.

### Horizontal scroll and swipe cards

These cards hold other cards. Select one in edit mode, pick a card type under **Cards** and press **Add**. The new card opens straight away so you can set it up; **←** takes you back. Use the arrows to reorder cards, and open a card to change or remove it.

- **Horizontal scroll** puts its cards in a row you can scroll sideways, by touch, trackpad or the arrow buttons that appear on hover. Set the card width in pixels, or as the number of cards visible at once (2.5 lets half a card peek out, so it's clear the row scrolls). A single card can get its own width in its settings. Add an optional title. The row keeps its scroll position when something inside it changes.
- **Swipe cards** shows one card at a time, filling the whole card. Swipe with a finger or drag with the mouse: the card follows along, resists at the first and last card, and a quick flick is enough. The left and right arrow keys work too. Small dots appear at the bottom while you swipe or hover, and hide again after a few seconds; tap one to jump to that card. It can also move to the next card automatically every few seconds. Touching it pauses that for 20 seconds, and it stops completely when the system's "reduce motion" setting is on.

Cards inside a container work like anywhere else, and appliance cards inside them still hide themselves when the appliance is off. When none of its cards are showing, the container shows a short message: change it with **Text when none of its cards are showing**, or tick **Hide this card when none of its cards are showing** to hide the container itself.

### Light groups

When the light card points at a light group, it becomes a control panel for the whole group: a switch and brightness slider for all lights at once, a row of white tones and colors (shown when the lights support them), and every light in the group with its own switch and brightness slider. Tap a light's colored dot to open its own panel with brightness, color temperature, colors and a free color picker. When you pick a group, the card grows to four rows so the list fits. Turn off **For a light group, show each light** to hide the list.

Tapping a light anywhere else on the dashboard (for example in a room card) opens the same light panel.

### To-do and shopping lists

Pick a to-do list (`todo.*`, such as Home Assistant's shopping list). Add items in the field at the top, tick them off, and swipe an item to the left (or use its delete button) to remove it. Completed items are hidden unless you turn on **Show completed items**; there's also a toggle in the card.

### Who's home

Shows each person (`person.*`, or everyone when you leave the list empty) with their photo or initials, home or away, how long they've been there or away, and the zone they're in. Choose a grid or a list.

### Weather forecast

An hourly strip (temperature, icon and chance of rain) and the next days with highs, lows and rain chance, from any weather entity. Choose hourly, daily or both, how far ahead, and whether to show today's sunrise and sunset (from `sun.sun`).

### Timer

For Home Assistant timer helpers (`timer.*`). A ring counts down with the time left. Start it with the quick-start buttons (5, 10, 15 and 30 minutes by default, which you can change), and pause, resume or cancel it. When the timer finishes, the card beeps (you can turn that off) and shows that it's done for a minute, or until you tap **OK**.

### Blinds and covers

Lists blinds, curtains or shutters (`cover.*`) with a position slider, a tilt slider for blinds that tilt, and open, stop and close buttons. **Open all** and **Close all** control every cover in the card at once.

### Alarm

An alarm panel (`alarm_control_panel.*`) with its state, a keypad for the code (shown when the panel asks for one), and buttons for the arming modes it supports. Add the doors and windows to check, or leave it empty to check every door and window sensor: open ones are listed, and arming asks for confirmation while something is open.

### Notifications

Home Assistant's notifications, with a button to dismiss each one or all, plus available updates (`update.*`) with a button to install them (after confirmation).

### Vacuum

The card grows with its size. On a small card it's a compact row with the status, battery and buttons. On a bigger card, the robot sits in the middle with a battery ring around it, a pulse while it cleans and a bolt while it charges. Below it are tiles for battery, cleaned area, cleaning time and any extra sensors you add (such as filter or brush life), the suction power levels, and labelled buttons to start or pause, send it back to the dock and locate it. Optionally add a map: pick the camera or image entity that your vacuum integration provides (for example Roborock or Valetudo), and it refreshes every few seconds. If the battery level is a separate sensor in your integration, pick it under **Battery sensor**.

### Energy

A live picture of where your power goes. Choose the sensors you have; all are optional except one:

- **Solar power**, **Grid power** (positive when you take power from the grid; tick the box if your meter is the other way round), **Battery power** (positive while charging, with the same kind of box) and **Battery level**.
- **Home use**, or leave it empty and the card works it out from the others.
- **Totals for today**, such as kWh produced and used, shown underneath.

Solar, the grid, the battery and your home are connected by lines. Moving dots show where power is flowing, and the more power, the thicker and faster the line. Solar power goes to the home first, then into the battery, and the rest back to the grid.

### Room

Pick one of your Home Assistant rooms (areas) and the card gathers everything in it:

- the room's temperature and humidity (the sensors set on the area in Home Assistant, or any temperature and humidity sensor in the room; you can also choose them yourself)
- chips for what's going on: how many lights are on (tap to switch them all off, or all on), the thermostat (tap it for the climate popup with a dial, −/+, modes, presets and fan modes), open doors and windows, motion, and music that's playing
- buttons for the lamps, switches, fans, covers and locks in the room

Light groups are left out so each lamp counts once. Add extra entities, or skip the room and list the entities yourself. The card glows warm while lights are on, and can have a background photo. Rooms are read from Home Assistant's area, device and entity registries.

### Media players

One card can control several players. With more than one, a row of buttons at the top switches between them, and a small animated equalizer marks the ones that are playing. The card starts on whatever is playing. It shows the album art, title and artist, with previous, play/pause and next buttons and a volume slider. A player that is off gets a **Turn on** button instead. You can hide players that are off from the switcher.

### Appliance (washer, dryer, dishwasher)

At two rows high, a progress ring around the appliance sits beside its name, status, program, the time left and when it will be ready, plus the door and its power or energy use. Taller cards stack the ring on top. Without a progress sensor, progress is worked out from the time left. It works with any integration, such as Home Connect, Miele, LG ThinQ, SmartThings, or a smart plug:

- **Status:** a sensor such as `sensor.washer_status`. Values like *running*, *washing*, *drying*, *finished* or *klaar* are recognized.
- **Power:** if there's no status, a power sensor works too. The appliance counts as running above the number of watts you set (5 W by default).
- **Time remaining:** minutes, hours, or an end time.
- **Progress** (%) and **Program** are optional.

By default the card only shows while the appliance is running or has just finished, and hides itself when it's off.

**Home Connect** (Bosch, Siemens, Neff, Gaggenau): choose the appliance's *Operation state* sensor as the status, and the card fills in the rest of the same device by itself: program progress, finish time, door state, active program, the pause, resume and stop buttons, the power switch and alerts (for example rinse aid or salt nearly empty, which Home Connect provides as event sensors that are off by default). Fields you already filled in are left alone. The card understands every Home Connect operation state: running, paused, finished, starts later (with the time it will be ready), action needed, error and stopping; *ready* and *inactive* count as off. Program names such as `dishcare_dishwasher_program_eco_50` show as "Eco 50". Depending on the state, round buttons appear to pause, resume or stop the program, or to switch the appliance on. While an alert is active, the card stays visible even when the appliance is off.

### Car

Point the car widget at whichever entities your car integration provides. Each one is optional:

| Field | Typical entity |
| --- | --- |
| Battery or fuel level (%) | `sensor.<car>_battery` |
| Range | `sensor.<car>_range` |
| Charging | `binary_sensor.<car>_charging` |
| Charging power | `sensor.<car>_charging_power` |
| Plugged in | `binary_sensor.<car>_plug` |
| Charge limit (%) | `number.<car>_charge_limit` |
| Doors | `lock.<car>_doors` |
| Climate | `climate.<car>_climate` |
| Location | `device_tracker.<car>_location` |
| Odometer | `sensor.<car>_odometer` |

Two optional extra fields: **Time until full** (a sensor in minutes or an end time) and **Start/stop charging** (a switch or button).

The card is designed around 3×4. It shows a drawn car (or your own photo) that glows with a bolt while charging, a round gauge with the charge level, the range in the middle and the charge limit marked, a status (charging with its power and when it will be full, plugged in, parked at home or away) and round buttons for the doors, climate, charging and location. On a short card it becomes a compact strip, on a wide card the car sits beside the numbers, and a tall card adds tiles for the odometer, charge limit and charging power. You can add a car image by URL. Images you put in Home Assistant's `www` folder are available at `/local/…`.

## Conditional widgets

Any widget can be shown only under certain conditions. Select it in edit mode, then under **Visibility** choose **Add condition**. Pick an entity, a comparison (*is*, *is not*, *above*, *below*) and a value. For example: *switch.coffee_machine is on*, or *sensor.washer_power above 5*. With several conditions, choose whether all of them or just one must be true.

In edit mode, hidden widgets stay visible but faded, with a **Hidden now** label, so you can still edit them. On the dashboard they disappear, and rows that only held hidden widgets close up so no gaps are left. Changes happen live as the entities change.

## Phone dashboards

Turn on **Designed for phones** under **Grid** in the dashboard settings. The dashboard switches to a 4-column layout that you design at phone width, so what you see while editing is what the phone shows. Existing widgets are converted: small tiles become half width, larger cards full width, and nothing overlaps. Turning it off converts back to 12 columns.

On a phone, such a dashboard fills the whole screen, without the top bar with the dashboard picker and **Edit**. To bring the bar back, touch and hold an empty spot for a moment; it hides again after 10 seconds. On a computer, a phone dashboard shows as a phone-width column. Dashboards that aren't designed for phones keep reflowing into two columns on phones, with the top bar.

## Tabs and side menu

A dashboard can have several tabs, each with its own widgets, for example *Overview*, *Household* and *Cameras*. To set them up, deselect all widgets in edit mode and use the **Tabs** section of the dashboard settings:

- **Add tab** creates a tab and turns on the menu.
- Each tab has a name and an icon (an icon name or an emoji). Use the arrows to reorder tabs and the bin to delete one; ⌘Z undoes this.
- **Show tabs in a side menu** turns the menu on or off.
- **Menu style:** *Icons only* (the default) shows a slim rail along the left edge, with the icons centered and a marker on the current tab. Hovering over an icon, or reaching it with the keyboard, shows the tab's name. *With names* shows the names next to the icons.

On phones the menu turns into a tab bar at the bottom, which always shows the names, since a phone has no hover. To move a widget to another tab, select it and change **Tab** in the inspector. The menu also shows in kiosk mode.

## Kiosk mode

Press **Kiosk** in the toolbar, or open the dashboard with `#kiosk` at the end of its address. Kiosk mode:

- hides the toolbar and editing panels, and shows no buttons of its own
- keeps the screen awake, in browsers that support it
- hides the pointer after a few seconds of no movement
- can show a screen saver after a number of minutes (set this in the dashboard's **Kiosk** settings): a dimmed clock, or a slideshow of photos from image links or Immich albums with the time in the corner
- can show the doorbell camera full screen when someone rings (see below)

**Leaving kiosk mode:** tap the top-right corner of the screen 5 times within a couple of seconds. A short prompt appears with **Leave kiosk**, **Full screen** and **Stay**. If nobody answers, it closes by itself after 8 seconds. Taps in that corner never press the widget underneath. On a keyboard, Escape opens the same prompt. You can move the exit gesture to another corner in the dashboard's **Kiosk** settings. A short hint shows when kiosk mode starts, then disappears.

**Doorbell:** in the **Kiosk** settings, pick the doorbell (a binary sensor that turns on, an `event.*` doorbell entity, or a switch or helper) and the camera to show. When it rings while kiosk mode is on, the camera fills the screen with a live picture, the screen saver goes away and a short chime plays (you can turn that off). It closes by itself after a minute, or after the number of seconds you set, or when you tap **Close**.

On a wall tablet, use **New tab** in the kiosk settings. It opens the dashboard on its own, without the Home Assistant sidebar, and full screen works there.

## Language and night mode

Dashboard Studio is available in English and Dutch (Nederlands). By default it follows the language you chose in your Home Assistant profile, or your browser's language if that isn't set. To choose a language for one device, such as a wall tablet, deselect all widgets in edit mode and use **Language on this device** under **This device** at the bottom of the dashboard settings. The app's Configuration tab in Home Assistant is translated as well.

**Night mode** is set per device in the same place. Choose **After sunset** (using `sun.sun`) or **Between times**, how much to dim the screen, and whether to switch to the dark theme. It turns on and off by itself, and is off while you're editing.

## Several dashboards

Use **＋** for a new dashboard. The **⋯** menu (in edit mode) can rename, duplicate, export, import or delete a dashboard. Exported JSON files can be imported on another Home Assistant install.

**Version history…** in the **⋯** menu lists the earlier saves of the dashboard, up to 30, with the time and the number of widgets. Changes made within five minutes of each other count as one version. **Restore** brings a version back; ⌘Z undoes that.

## Which dashboard opens where

Use **⋯ → Who sees which dashboard…** in edit mode to choose the dashboard that opens first:

- **This device:** give the device a name, for example *Kitchen tablet*, and pick its dashboard. Tick **Kiosk** to have it start in kiosk mode.
- **Other devices** you have named appear in the list too, so you can change them from anywhere.
- **People:** pick a dashboard per Home Assistant user. People appear once they've opened Dashboard Studio, or when they have a person entity.

A device's choice comes before a person's. Without either, the last dashboard used on that device opens. A link with `#view=…` always wins. You can still switch dashboards at any time.

## Version and updates

The version you're running is shown at the bottom of the dashboard settings, under **About** (deselect all widgets in edit mode). **What's new** there shows the changelog, which is also on the app's **Changelog** tab in Home Assistant. After an update, a short message points you to it. After Home Assistant installs an update, screens that are open reload themselves within a few minutes, which is handy for wall tablets. While you're editing, you get a message instead, so nothing you're working on is interrupted.

## Data

Dashboards are stored in the app's `/data/dashboards.json`, and their version history in `/data/history/`, so both are included in Home Assistant backups.