# kiosk-mode: hiding the Home Assistant header and sidebar for a wall display

> kiosk-mode is a Home Assistant Lovelace plugin that hides the header and the sidebar drawer so a dashboard can run on a wall tablet without navigation chrome. It installs through HACS or as a single JavaScript file, its configuration is a per dashboard YAML block, and its version must be matched to your Home Assistant release.

**NemesisRE/kiosk-mode** — 🙈 Hides the Home Assistant header and/or sidebar

- Repository: https://github.com/NemesisRE/kiosk-mode
- Stars: 818 · Forks: 36
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/nemesisre-kiosk-mode

## A dashboard with the navigation chrome removed

kiosk-mode does one thing: it hides the header and, optionally, the sidebar drawer in Home Assistant Lovelace dashboards. The plugin description says exactly that, and the repository topics are customization and hacs, which tells you the intended install route.

The use case is a display that should look like an app rather than like an administration console. A wall tablet running a temperature dashboard looks wrong with a hamburger menu in the corner and a sidebar that slides out when a visitor brushes the screen. Removing them turns the same dashboard into something you can leave on a wall.

Two configuration keys drive it, and the README shows both in a single block.

```yaml
kiosk_mode:
  hide_header: true
  hide_sidebar: '{{ is_state("input_boolean.hide_sidebar", "on") }}'
views:
```

The hide_header value is a plain boolean. The hide_sidebar value in the example is a template that evaluates to a state of an input boolean entity, which is the interesting part: the sidebar can be hidden conditionally, so you can bring it back temporarily on demand without editing the dashboard. The trailing views key is included in the README example only to show where the kiosk_mode block belongs.

The plugin is a frontend resource, not a server component, so it runs in the browser of whatever device renders the dashboard.

## The compatibility table decides which version you install

The most consequential part of the README is a five item compatibility list, because it says that installing the latest release is not always possible. Each entry maps a Home Assistant version range to the plugin version that supports it.

The rules run in steps. If Home Assistant 2025.5.1 or greater is installed, the minimum compatible plugin version is v7.0.0, and anything below that Home Assistant version is limited to v6.7.0. For Home Assistant 2025.10.0 or greater, the minimum is v8.0.0, and a version between 2025.5.1 and 2025.10.0 tops out at v7.4.0. For Home Assistant 2026.2.0 or greater, the minimum is v10.0.0, and a version between 2025.10.0 and 2025.1.3, as the README writes it, tops out at v9.0.2. For Home Assistant 2026.3.0 or greater, the minimum is v11.0.0, and a version between 2025.2.0 and 2025.2.3 tops out at v10.0.0. For Home Assistant 2026.6.0 or greater, the minimum is v14.0.0, and a version between 2025.3.0 and 2025.6.0 tops out at v13.1.0.

Read that as a floor plus a ceiling for every Home Assistant release. The plugin follows the Home Assistant release train closely enough that the version pair changes several times a year, and the fact that a v6.7.0 from the 2025 era and a v15.0.0 from late 2026 both exist tells you how fast the numbering moves.

The practical effect is that a Home Assistant user cannot blindly install the newest release. The table in the README is the thing to read first, and the wording of the entries themselves has inconsistencies in the version ranges, so treat them as guidance and check the release you pick against the Home Assistant version you run.

## Installing through HACS, with the YAML fallback

The README insists that you follow one of two routes, HACS or manual, and the HACS route is the one most people will take.

The HACS path is short if the My Home Assistant integration is enabled, because a direct link goes to the plugin page. Otherwise you open the HACS dashboard, search for Kiosk Mode, and open its page. On that page the Download button in the bottom right corner opens a more-info dialog with a second Download button in it.

There is one manual step left even after that, and it depends on how you run Home Assistant. If you are in YAML mode, or if HACS did not add the resource for you, the file has to be registered in your configuration.yaml as an extra module url, and the path depends on where HACS put it.

```yaml
frontend:
  extra_module_url:
    - /hacsfiles/kiosk-mode/kiosk-mode.js
```

The path is the one HACS uses for its own files, and the frontend key is the standard place to register additional frontend modules.

The repository is a HACS default integration, and the CI configuration includes a HACS action that checks the hacs.json metadata, so the packaging side is automated rather than maintained by hand.

## The manual route is one file in the www folder

The manual installation is a single JavaScript file, and it works because the plugin ships as a bundled build artifact. The dist directory in the repository is where that bundle lives, and the package manifest points at kiosk-mode.js as the main entry.

The steps are to download kiosk-mode.js from the latest release, place it in your www folder, and then register the file as a frontend resource. In storage mode, which the README calls the default mode, you add the resource through the interface, by going to Settings, then Dashboards, then the three dots in the top right corner, then Resources, then ADD RESOURCE, and giving the URL of the file you just downloaded.

The URL needs a version query string, and the README is emphatic about why, since otherwise Home Assistant keeps serving the cached copy instead of the new file.

```yaml
frontend:
  extra_module_url:
    - /local/kiosk-mode.js?v1.0.0
```

The example URL ends with a version marker, and the accompanying comment says to update that number after every update to avoid the old version being cached. The same advice appears in the storage mode instructions, which give the example /local/kiosk-mode.js?v=1.0.0 form. The two examples differ slightly in punctuation, which is a small inconsistency in a file where the version suffix is the whole mechanism.

There is also a troubleshooting path for anyone who gets stuck, a community wiki page on Lovelace plugin installation, and a video walkthrough linked from the README.

## The default dashboard will not work, and that catches people out

The Important Info section carries the single most important operational fact about the plugin, and it is a limitation rather than a feature.

Since Home Assistant 2023.12.0 it is possible to access the raw configuration of a Default dashboard that Home Assistant itself controls. Any configuration you add to such a dashboard is ignored, so kiosk-mode cannot read it. The fix is to create a New dashboard from scratch that you control, and only then does the plugin have a config to read.

That means a fresh install of the plugin on a default dashboard appears to do nothing, and the natural reaction is that the plugin is broken. It is a different failure, and the README is explicit about the cause.

Three further rules come with it. The kiosk_mode key must sit at the root of the Lovelace config and must not be indented, and it is per dashboard, so any other dashboard you want affected needs the same block repeated in it. And a page refresh is needed after a configuration change, which matters when you are editing from a tablet on the wall and wondering why nothing happened.

There is also an escape hatch for testing. Adding ?disable_km to the end of the URL turns the plugin off for that load, which is the fastest way to get the header back without touching the dashboard configuration at all.

## Rollup for the bundle, Playwright and Docker for the tests

The repository is a modern TypeScript project with a build pipeline and a real test setup, and the package scripts show how the pieces fit together.

```json
{
  "name": "kiosk-mode",
  "version": "15.0.0",
  "description": "Hides the Home Assistant header and/or sidebar",
  "type": "module",
  "main": "kiosk-mode.js",
  "license": "MIT",
  "scripts": {
    "build": "rollup --config rollup.config.mjs",
    "test:ts": "tsc --noEmit",
    "test:all": "pnpm lint && pnpm test:ts && pnpm test:ci",
}
}
```

The build is rollup, producing the single file that the installation instructions tell you to download, which is why the distributed artifact is a plain JavaScript file rather than a package with dependencies. Linting is eslint over the source and the tests, and the TypeScript check is a no emit compile, so type errors fail the pipeline without producing output.

The interesting part is the test setup. The tests are Playwright browser tests, and they run against a real Home Assistant instance started in Docker, with a local configuration directory mounted at .hass/config and the Home Assistant version read from a .HA_VERSION file inside it. The container is published on port 8123, and the Playwright container is given host access so the browser can reach it. There is a separate script for running only the tests tagged as testing, and a script to update the snapshots, with a test-snapshots directory in the repository holding the expected output.

There is also a nightly beta test workflow, which is how a plugin that has to match a fast moving platform stays ahead of Home Assistant releases, a coverage report through nyc, and renovate for dependency updates.

## Conclusion

kiosk-mode fits a Home Assistant user with a tablet or panel running a dashboard full screen, who controls that dashboard and can add a YAML resource entry, and who is willing to pick the plugin version that matches their Home Assistant release. It does not fit a user of a Home Assistant controlled default dashboard, since the configuration of those is ignored and the plugin cannot read it. Verify first that you have a dashboard created from scratch under your own control, that the kiosk_mode block sits at the root of that dashboard config and is repeated for each dashboard you want affected, and that the version you install is the one the compatibility table names for your Home Assistant version, since the last push was on 2026-10-19 and the plugin tracks Home Assistant releases closely.

## FAQ

### How do I install kiosk-mode in Home Assistant?

Follow one of two routes. Through HACS, open the plugin page from the HACS dashboard and use the Download button, then register the file as a frontend resource. Manually, download kiosk-mode.js from the latest release into your www folder and add it as a resource, in storage mode through the Resources screen or in YAML mode as an extra_module_url.

### Which version of kiosk-mode works with my Home Assistant release?

The README lists a compatibility table. For example, Home Assistant 2025.5.1 or greater needs kiosk-mode v7.0.0 or later, Home Assistant 2025.10.0 or greater needs v8.0.0 or later, and Home Assistant 2026.6.0 or greater needs v14.0.0 or later, with an upper bound listed for each earlier Home Assistant range.

### Why does kiosk-mode do nothing on my default dashboard?

Since Home Assistant 2023.12.0 the raw configuration of a Default dashboard is accessible, and any configuration added to it is ignored, so the plugin cannot read it. You need a New dashboard from scratch that you control for the kiosk_mode settings to take effect.

### How do I hide the Home Assistant sidebar only when I need it?

The hide_sidebar value accepts a template, and the README example uses a state of an input boolean entity, so the sidebar can be tied to a helper. To turn the plugin off temporarily instead, add ?disable_km to the end of the dashboard URL.

### Where does the kiosk_mode configuration go in a Lovelace dashboard?

At the root of the Lovelace configuration, not indented, and it applies per dashboard, so the same block has to be repeated on each dashboard you want affected. YAML mode users edit the dashboard file directly, and storage mode users use the Raw configuration editor in Edit Dashboard mode. A page refresh is needed after a change.

## Sources

- [Issues](https://github.com/NemesisRE/kiosk-mode/issues)
- [License: MIT](https://github.com/NemesisRE/kiosk-mode/blob/master/LICENSE)
- [NemesisRE/kiosk-mode on GitHub](https://github.com/NemesisRE/kiosk-mode)
- [README](https://github.com/NemesisRE/kiosk-mode/blob/master/README.md)
- [Releases](https://github.com/NemesisRE/kiosk-mode/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nemesisre-kiosk-mode