Skip to content

v12.1.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 09 Feb 22:08
v12.1.0
d696f4a

⚠️⚠️⚠️ RISK OF BREAKING CHANGE ⚠️⚠️⚠️

DO NOT UPDATE WITHOUT READING FIRST!!!

If you have not updated to Home Assistant 2026.2.0 yet, DO NOT UPDATE CUSTOM SIDEBAR, read the release notes of the version 12.0.0 first.

This release is a minor one and it doesn't represent a breaking change if you are already in custom-sidebar v12.0.0. It provides several ways of navigating to a panel in a programatic way.

New navigate action

There is a new navigate action to be used inside the on_click property.

Using a string in the path

Using a string as the path of a navigate action doesn't have any advantage over using the href property in an item.

- new_item: true
  item: 'Developer tools'
  icon: 'mdi:hammer-wrench'
  on_click:
    action: 'navigate'
    path: '/config/developer-tools'

Using a JavaScript template in the path

This is the real power of the navigate action. As you can use a JavaScript template in the path property, you can place a logic that will decide what will be the path to navigate when the item is clicked.

- new_item: true
  item: 'Decision item'
  icon: 'mdi:arrow-decision-outline'
  on_click:
    action: 'navigate'
    path: |
      [[[
        if (is_state('input_boolean.dev_mode_active', 'on')) {
          return '/config/developer-tools';
        }
        return '/lovelace';
      ]]]

Using the optional replace parameter

This parameter will decide if the path should be appended to the history (if it is omitted or if it is false) or if it should replace the current URL in the history (if it is true).

- new_item: true
  item: 'Developer tools'
  icon: 'mdi:hammer-wrench'
  on_click:
    action: 'navigate'
    path: '/config/developer-tools',
    replace: true

New navigate method

The navigate method should be used in a javascript action of the on_click property. It allows one to navigate to a dashboard path in a programatic way.

- new_item: true
  item: 'Developer tools'
  icon: 'mdi:hammer-wrench'
  on_click:
    action: 'javascript'
    code: |
        if (user_is_admin) {
          navigate('/config/developer-tools');
        } else {
          openAlertDialog({
            title: 'Error',
            text: 'Only admin users can go to this path',
            confirmText: 'Close'
          });
        }

The navigate method also accepts a second boolean parameter to indicate if the current URL in the history should be replaced by the new path or the new path should be appended to the history instead.

- new_item: true
  item: 'Developer tools'
  icon: 'mdi:hammer-wrench'
  on_click:
    action: 'javascript'
    code: 'navigate('/config/developer-tools', true);' ## true means replace the current URL

New activateItem method

This method allows one to make an item in the sidebar active programatically and it will deactivate the previous active item automatically. You need to send an ha-md-list-item element as parameter (inside an action of an on_click property, you can access the element property of the item variable to access the clicked ha-md-list-item). When you navigate to a path in a programatic way, the clicked item will not be selected because it doesn't have a href, the activateItem method can be used to solve this.

- new_item: true
  item: 'Developer tools'
  icon: 'mdi:hammer-wrench'
  on_click:
    action: 'javascript'
    code: |
        if (user_is_admin) {
          navigate('/config/developer-tools');
          activateItem(item.element);
        } else {
          openAlertDialog({
            title: 'Error',
            text: 'Only admin users can go to this path',
            confirmText: 'Close'
          });
        }

Notes:

  1. The path used for the navigate action or the navigate method needs to start with /. If you try to navigate to an absolute URL or a path that doesn't start with /, it will be ignored and a warning will be thrown in the console instead.
  2. You should not use the navigate action or the navigate method in an an item that contains an href property because the default functionality of redirecting to a dashboard taking into account the href and the navigate action/method functionality will clash.
  3. When you visit a URL directly, there is a logic to activate the proper sidebar item taking into account its href. You need to be aware that when using a navigate action or the navigate method programatically, there is no way for the plugin to know that an item redirects to a dashboard path, so in those cases the item will not be activated.

🚀 Features

🧩 Dependencies

  • [Dependencies]: Bump the dependencies-dev group with 4 updates

📝 Documentation

📦 Other

Contributors

elchininet and dependabot
Assets 5
Loading