hass-swipe-navigation: swiping between Home Assistant dashboard views

A fork of an unmaintained project, and the conflict that comes with it

The first thing the readme tells you is that this repository has been forked from maykar/lovelace-swipe-navigation, to continue the development since the original project is currently unmaintained. That framing is the history of the plugin in one sentence, and it has a practical consequence you are told about immediately. You are asked to uninstall the original lovelace-swipe-navigation before proceeding, as it will conflict with this plugin. Two plugins both hooking touch events and both transforming the dashboard will fight each other, and the failure mode would be a swipe that half works, which is the kind of bug that is tedious to trace. The acknowledgements thank the original author of the project, and the repository is MIT licensed with the licence file at the top level, so there is no licensing obstacle to the fork. The last push to the repository was on 2026-10-18, and the recent releases are v1.16.1 from 2026-09-06, v1.16.0 from 2026-04-11 and v1.15.8 from 2025-11-10, so this is a maintained line with a roughly quarterly release rhythm.

The feature list is mostly about what the swipe should ignore

The features are listed as a short set of behaviours, and the interesting ones are the negative cases. You can configure views to skip over, and you can set the swipe length needed to trigger a navigation. There is an option to disable the browser's default swipe actions, which otherwise fight the plugin on mobile browsers where a horizontal swipe is already bound to back navigation. You can wrap from the first view to the last and vice versa, so the swipe behaves like a carousel rather than stopping at the ends. It supports RTL languages, which matters for the layout logic as much as for the users. And it correctly ignores swipes over certain elements, with sliders and maps given as the examples, because a horizontal drag on a map or a slider is a gesture the user means and must not be stolen by the navigation. The last one is the feature that separates a usable plugin from an annoying one, since a map is a common dashboard tile.

The configuration is one YAML block under swipe_nav

If you want the default values you do not need a configuration at all, and that is stated up front. To change anything you place the options in the root of your dashboard configuration under the swipe_nav element. The example in the readme is explicitly labelled as something not to copy blindly.

# You don't necessarily need a configuration.
# Add only the options that differ from the default values.
swipe_nav:
  wrap: false
  enable_mouse_swipe: true
  animate: swipe
  skip_tabs: 5,6,7,8
  prevent_default: true
  swipe_amount: 30
views:

The options table is where the detail lives. The animate option takes none, swipe, fade or flip, with the swipe animation described as experimental and possibly buggy depending on your setup. animate_duration is in milliseconds and defaults to 200. enable turns the whole thing on or off and defaults to true, and enable_mouse_swipe is off by default. prevent_default controls the browser's own horizontal swipe behaviour and defaults to false. logger_level sets the logging verbosity, with verbose, debug, info, warn and error as the values, and warn as the default. The readme also links a video by Mark Watt covering the configuration, which is a faster route to understanding the options than reading the table.

skip_tabs counts from zero, and skip_hidden is deprecated for a reason

Two of the options have sharp edges that the readme flags in bold, and both are worth reading before you configure anything. The first is skip_tabs, a comma separated list of views to skip when swiping, with an example of 1,3,5, and a note that tab counting starts at 0, so the first is 0, the second is 1, and so on. That off by one is the kind of detail that produces a support question, because a list written as 5,6,7,8 in the example skips the sixth through ninth views rather than the fifth through eighth. The second is skip_hidden, which automatically skips hidden tabs, and the readme marks it as deprecated and says that setting it to false poses a security risk, because it allows a user to reveal a tab they do not have access to. A hidden tab in Home Assistant is a permissions decision, and letting a swipe reveal one undoes it. The readme also distinguishes skip_subviews, which skips over subviews while navigating from regular views, from enable_on_subviews, which enables swipe navigation while you are on a subview. Those two settings are easy to confuse and they do opposite things.

Installing through HACS, and the manual route with a versioned URL

The readme says to follow only one of the two installation methods. The recommended one is HACS, the Home Assistant Community Store. You open the repository from HACS, either through the badge or by searching for Swipe Navigation in the sidebar, where the entry is listed as Home Assistant Swipe Navigation, then select Download in the bottom right of the repository page. HACS adds the dashboard resource automatically, and if your dashboards are in YAML mode the dialog shows you the resource entry to add by hand instead, which is a real detail because a YAML dashboard has to reference the resource explicitly. You then confirm the browser reload. The manual route copies swipe-navigation.js from the latest release into /www/hass-swipe-navigation/, and adds the resource through Settings, then Dashboards, then the More Options icon, then Resources, then Add resource, with the URL set to the path below and the resource type set to JavaScript module.

# Increase the version number (`v=x.y.z`) at end of the URL after each update
url: /local/hass-swipe-navigation/swipe-navigation.js?v=1.0.0
type: module

The version query string matters for a reason that is in the comment: the browser caches the script, and without a changing version parameter an update can appear not to have taken effect. You then refresh the page, and the readme notes it may need a cache clear.

How the build and the test environment are put together

The repository is a TypeScript project built with Rollup, and the package.json is small enough to read at a glance. The build script runs rollup with the config file, and there is a watch variant for development. The only runtime dependency is zod, which suggests the configuration is validated at runtime rather than trusted blindly, and the devDependencies carry the rest: Rollup with the node resolve, terser and typescript plugins, TypeScript 6, ESLint 10 with the typescript-eslint plugin, Husky, Commitlint with commitizen, and Playwright for the end to end tests. The Playwright part is the interesting one, because a swipe plugin is exactly the kind of code that is hard to test with unit tests alone. The tree backs that up with a playwright.config.ts, a playwright.global-setup.ts and a playwright.global-teardown.ts, plus a docker-compose.yml that runs a builder service on port 3000 and a homeassistant/home-assistant:beta instance on port 8123, with the swipe navigation script URL injected as an environment variable and several config files mounted read-only from a .hass directory. The compose file also keeps node_modules in a named volume and syncs the host clock, which are the small touches that make a containerised test loop bearable.

Editorial conclusion

hass-swipe-navigation fits a Home Assistant installation whose dashboards are used from a phone and where the sidebar is either hidden or in the wrong place for one handed use, because the whole plugin is a small amount of touch handling layered on the dashboard you already have. It does not fit a desktop-first installation, where mouse swiping is off by default, and it does not suit you if you are still running the original lovelace-swipe-navigation, since the two conflict and the readme asks you to uninstall the original first. Before you install, decide whether you want the animated transition, which the readme calls experimental and potentially buggy depending on your setup, and check the skip_tabs indexing, because tab counting starts at zero, so the example values 5,6,7,8 skip the sixth through ninth views rather than the fifth through eighth.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zanna-37/hass-swipe-navigation on GitHub