Home

Awesome

kiosk-mode

hacs_badge CodeQL HACS Action Test Coverage Status release downloads

Hides the header and/or sidebar drawer in Home Assistant lovelace dashboards.

image

Installation

Follow only one of two installation methods below, HACS or Manually:

If you want to learn how to install and set some basic configurations in kiosk-mode through a video, check the next one from @smarthomejunkie.

<details> <summary><b>Installation through HACS</b></summary> <br>
  1. In the "Frontend" section of HACS hit the plus icon in the bottom right
  2. Search for Kiosk Mode and install it
  3. If using YAML mode or if HACS doesn't automatically add it, you'll need to add the resource manually:

Go to your configuration.yaml file and add the url of the plugin as an extra_module_url:

# You should update the version number at the end of the url
# after every update to avoid the old version being cached by Home Assistant
frontend:
  extra_module_url:
    - /hacsfiles/kiosk-mode/kiosk-mode.js?v1.0.0
<br> </details> <details> <summary><b>Manual installation</b></summary> <br>
  1. Download kiosk-mode.js from the latest release and place it in your www folder
  2. Add the resource:

If you are in storage mode (default mode)

  1. Go to Settings > Dashboards
  2. Click on the three dots located on the top-right corner and then click on Resources
  3. Click on ADD RESOURCE on the bottom-right of the screen
  4. Add the URL to the file that you have downloaded previously (e.g /local/kiosk-mode.js?v=1.0.0)
  5. Make sure you add the correct version at the end of the URL (e.g. ?v=1.0.0) because in this way you make Home Assistant to load the new version instead of a version stored in cache

If you are in yaml mode

Go to your configuration.yaml file and add the url of the plugin as an extra_module_url:

# You should update the version number at the end of the url
# after every update to avoid the old version being cached by Home Assistant
frontend:
  extra_module_url:
    - /hacsfiles/kiosk-mode/kiosk-mode.js?v1.0.0
<br> </details>

If you have trouble installing please read this guide

Important Info

Simple config example

YAML mode users need to add the configuration manually to the lovelace dashboard file in which they want to enable kiosk-mode. Non-YAML users (Storage Mode) need to add the configuration to each lovelace panel going to Edit dashboard option (pencil icon on the top-right of the screen). Once in Edit Dashboard mode, click on the top-right three-dots button and select Raw configuration editor.

kiosk_mode:
  hide_header: true
  
views:

Note: views: is added in the example above to show where kiosk_mode: should be placed in your Lovelace config<br><br>

Config Options

Config OptionTypeDefaultDescription
kioskBooleanfalseHides both the header and sidebar.
hide_header<sup>1</sup>BooleanfalseHides only the header.
hide_sidebarBooleanfalseHides only the sidebar.
hide_menubutton<sup>1</sup>BooleanfalseHides only the sidebar menu icon.
hide_notificationsBooleanfalseHide the notifications entry-point.
hide_accountBooleanfalseHides the account icon.
hide_searchBooleanfalseHides the search icon.
hide_assistantBooleanfalseHides the assistant icon.
hide_overflowBooleanfalseHides the top right overflow menu.
block_overflowBooleanfalseBlocks the top right overflow menu mouse interactions.
hide_refreshBooleanfalseHides the "Refresh" button inside the top right overflow menu in lovelace yaml mode.
hide_unused_entitiesBooleanfalseHides the "Unused entities" button inside the top right overflow menu in lovelace yaml mode.
hide_reload_resourcesBooleanfalseHides the "Reload resources" button inside the top right overflow menu in lovelace yaml mode.
hide_edit_dashboardBooleanfalseHides the "Edit dashboard" button inside the top right overflow menu.
block_mouseBooleanfalseBlocks completely the mouse. No interaction is allowed and the mouse will not be visible. Can only be disabled with ?disable_km query parameter in the URL..
block_context_menuBooleanfalsePrevents opening a right-click context menu (sometimes accessible via tap-and-hold on touchscreen devices).
hide_dialog_header_historyBooleanfalseHides the "History" icon in the header of more-info dialogs.
hide_dialog_header_settings<sup>2</sup>BooleanfalseHides the "Settings" icon in the header of more-info dialogs.
hide_dialog_header_overflow<sup>2</sup>BooleanfalseHides the top right overflow menu in the header of more-info dialogs.
hide_dialog_header_action_itemsBooleanfalseHides all the action items from the header of more-info dialogs.
hide_dialog_historyBooleanfalseHides the "History" section in the more-info dialogs.
hide_dialog_history_show_moreBooleanfalseHides the "Show more" link in the "History" section of more-info dialogs.
hide_dialog_logbookBooleanfalseHides the "Logbook" section in the more-info dialogs.
hide_dialog_logbook_show_moreBooleanfalseHides the "Show more" link in the "Logbook" section of more-info dialogs.
hide_dialog_attributesBooleanfalseHides the "Attributes" section in the more-info dialogs.
hide_dialog_media_actionsBooleanfalseHides the actions block in the more-info dialogs of media-player entities.
hide_dialog_update_actionsBooleanfalseHides the actions block in the more-info dialogs of update entities.
hide_dialog_timer_actionsBooleanfalseHides the actions block in the more-info dialogs of timer entities.
hide_dialog_climate_actionsBooleanfalseHides all the actions in the more-info dialogs of climate entities.
hide_dialog_climate_temperature_actionsBooleanfalseHides the temperature cotrol actions in the more-info dialogs of climate entities.
hide_dialog_climate_settings_actionsBooleanfalseHides the mode and preset actions in the more-info dialogs of climate entities.
hide_dialog_light_actionsBooleanfalseHides all the actions in the more-info dialogs of light entities.
hide_dialog_light_control_actionsBooleanfalseHides the control actions in the more-info dialogs of light entities.
hide_dialog_light_color_actionsBooleanfalseHides the favorite colors actions in the more-info dialogs of light entities.
hide_dialog_light_settings_actionsBooleanfalseHides the settings actions in the more-info dialogs of light entities.
ignore_entity_settings<sup>3</sup>BooleanfalseUseful for conditional configs and will cause entity_settings to be ignored.
ignore_mobile_settings<sup>4</sup>BooleanfalseUseful for conditional configs and will cause mobile_settings to be ignored.
ignore_disable_km<sup>3</sup>BooleanfalseUseful for conditional configs and will cause disable_km URL parameter to be ignored.
<br/>

<sup>1</sup> Take into account that swipe gesture to open the sidebar was removed from Home Assistant in version 2023.4, if you hide the header or the sidebar menu icon, you will not have any way to access the sidebar natively in a browser.

<sup>2</sup> These elements are not visible by default if the account is not an admin account.

<sup>3</sup> These options only work if they are placed inside admin_settings, non_admin_settings, user_settings or mobile_settings. They will not have any effect if they are placed inside entity_settings

<sup>4</sup> This option only works if it is placed inside admin_settings, non_admin_settings or user_settings. It will not have any effect if it is placed inside mobile_settings or entity_settings

<br/>

Options through screenshots

<br>

Lovelace Dashboard <br>Lovelace dashboard <br>

OptionsHides / Blocks
kiosk1 and 2
hide_header1
hide_sidebar2
hide_menubutton3
hide_notifications4
hide_account5
hide_search6
hide_assistant7
hide_overflow8
block_overflow8
block_mousewhole interface
block_context_menuright click anywhere
<br>

Lovelace Dashboard <br>Overflow menu <br>

OptionsHides
hide_refresh9
hide_unused_entities10
hide_reload_resources11
hide_edit_dashboard12
<br>

Lovelace Dashboard <br>More info dialog (media entity) <br>

OptionsHides
hide_dialog_header_action_items13
hide_dialog_header_history14
hide_dialog_header_settings15
hide_dialog_header_overflow16
hide_dialog_media_actions17
<br>

Lovelace Dashboard <br>More info dialog (climate entity) <br>

OptionsHides
hide_dialog_climate_actions18
hide_dialog_climate_temperature_actions19
hide_dialog_climate_settings_actions20
<br>

Lovelace Dashboard <br>More info dialog (light entity) <br>

OptionsHides
hide_dialog_light_actions21
hide_dialog_light_control_actions22
hide_dialog_light_color_actions23
hide_dialog_light_settings_actions24
<br>

Lovelace Dashboard <br>More info dialog (update entity / timer entity) <br>

OptionsHides
hide_dialog_update_actions25
hide_dialog_timer_actions25
<br>

Lovelace Dashboard <br>More info dialog (sensor entity) <br>

OptionsHides
hide_dialog_history26
hide_dialog_logbook27
hide_dialog_attributes28
hide_dialog_history_show_more29
hide_dialog_logbook_show_more30
<br>

Conditional Lovelace Config

Contitional configs take priority and if a condition matches all other config options/methods are ignored. These use the same options as above, but placed under one of the following user/entity conditions:<br><br>

admin_settings:

Sets the config for every admin user.<br> Overwritten by user_settings, mobile_settings, and entity_settings ( unless one of the ignore options is used ).<br>

kiosk_mode:
  admin_settings:
    hide_header: true
<br>

non_admin_settings:

Sets the config for every regular user.<br> Overwritten by user_settings, mobile_settings, and entity_settings ( unless one of the ignore options is used ).<br>

kiosk_mode:
  non_admin_settings:
    hide_header: true
    ignore_entity_settings: true
<br>

user_settings:

Sets the config for specific users. This uses a user's name, not their username (if they're different).<br> Overwritten by mobile_settings, and entity_settings ( unless one of the ignore options is used ).<br>

kiosk_mode:
  user_settings:
    - users:
        - "ryan meek"
        - "maykar"
      hide_sidebar: true
    - users:
        - "the wife"
      kiosk: true
      ignore_entity_settings: true
<br>

mobile_settings:

Sets the config for mobile devices. The default breakpoint is 812px, which can be changed by setting the custom_width option.<br> Overwritten by entity_settings, unless ignore_entity_settings is used, can be ignored with ignore_mobile_settings.<br>

kiosk_mode:
  mobile_settings:
    hide_header: true
    ignore_entity_settings: true
    custom_width: 768
<br>

entity_settings:

Dynamically change config on any entity's state. Under entity: list the entity followed by the state that will enable the config below. For more complex logic use this with a template sensor.<br> Takes priority over all other config settings unless they use ignore_entity_settings.<br><br>

Any condition that doesn't match will then fall back to previous configurations if another "false" entity condition hasn't also been set (see the 2nd example).

kiosk_mode:
  entity_settings:
    - entity:
        input_boolean.hide_sidebar: 'on'
      hide_sidebar: true
    - entity:
        sensor.hide_header: 'on'
      hide_header: true
    - entity:
        input_text.kiosk: 'true'
      kiosk: true
kiosk_mode:
  entity_settings:
    # hide_sidebar has both true and false conditions to be a true override.
    - entity:
        input_boolean.hide_sidebar: 'on'
      hide_sidebar: true
    - entity:
        input_boolean.hide_sidebar: 'off'
      hide_sidebar: false
<br>

Query Strings

Add a query string such as ?kiosk to the end of your URL:

https://hass:8123/lovelace/default_view?kiosk

If you need to add multiple query parameters, you need to separate them by & (only the first parameter should be prepended by ?):

https://hass:8123/lovelace/default_view?hide_header&hide_sidebar

The query string options are:

Query String Caching

You save settings in a devices cache by using the cache keyword once on the device.<br>This will also make it so the options work on all views and dashboards.

Example: ?hide_header&cache makes all views & dashboards hide the header.<br> This works for all query strings except for the utility strings listed below.

Utility Query Strings

Kiosk-mode demo

Kiosk-mode complements

Some features are outside kiosk-mode scope and they would be hard to maintain and escalate over time, but they could be achieved by alternative methods. Check kiosk-mode complements for this.

Related

Credit

This was originally based on and inspired by ciotlosm's kiosk mode gist and corrafig's fork of the same gist.

Big thank you to matt8707 for starting this project, allowing me to rewrite it, and transfering ownership.

Many thanks to KTibow as well, for the github release action and support.

And another big thanks to maykar for the original kiosk mode