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.

## Look and feel

- **Theme:** *System* follows your device's light or dark appearance. Light, Dark, Nord, Dusk and Forest are fixed themes. 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, type an icon name (the field suggests them) 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. 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.

### 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` |

The widget shows the level as a bar with the charge limit marked, the range, and a status line (charging and its power, plugged in, parked at home, or away). It also has buttons to lock or unlock the doors and to start climate. You can add a car image by URL. Images you put in Home Assistant's `www` folder are available at `/local/…`.

## 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.

The menu sits on the left on computers, becomes a narrow rail on tablets and while editing, and turns into a tab bar at the bottom on phones. 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 dimmed clock screen saver after a number of minutes (set this in the dashboard's **Kiosk** settings)

**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.

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

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** at the bottom of the dashboard settings. The app's Configuration tab in Home Assistant is translated as well.

## 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.

## Data

Dashboards are stored in the app's `/data/dashboards.json`, so they are included in Home Assistant backups.