DOCSEARCHbyAlgolia
Submit Docs

Custom Sidebar for Home Assistant

website·Indexed 30 days ago

https://elchininet.github.io/custom-sidebar

A customization tool for the Home Assistant sidebar that allows users to hide or show items dynamically, set default landing dashboards, and reorder items. It features a configuration system using custom-sidebar-config.yaml and supports both Jinja and JavaScript templates for advanced logic, including native Home Assistant dialogs, toast notifications, and REST API integration.

Tokens
15.8K
Snippets
60
Records
103
Agent score
75%

What's inside Custom Sidebar

  1. Set a default dashboard for a Home Assistant user

    To ensure a user lands on a specific dashboard when Home Assistant loads, navigate to the user's profile and locate the 'User preferences' section to select the default dashboard. Note that this setting is applied per user account, not per device; changing the default dashboard on a mobile device will also change it for the desktop device using the same account. To have different default dashboards on different devices, you must create and use separate user accounts for each device.

  2. Choose between JavaScript and Jinja templates for Custom Sidebar

    Custom Sidebar supports two templating systems for configuration options and item properties: JavaScript and Jinja.

    JavaScript Templates:

    • Rendered on the client device (faster processing).
    • Use a single subscribe_events WebSocket subscription for all templates to detect state changes.
    • Can access client-side data (DOM APIs), return Promises, use Reactive JavaScript Variables, and execute methods like opening dialogs or calling services.

    Jinja Templates:

    • Use the same templating system as Home Assistant.
    • Depend on render_template WebSocket calls to receive results, creating a separate subscription per template.
    • Limited to server-side logic; cannot access DOM APIs or execute client-side JavaScript methods.
    • To hide an element in specific scenarios, the template should return an empty string.

  3. Set a default dashboard for Home Assistant users

    To ensure a user lands on a specific dashboard when Home Assistant loads, configure the default dashboard within the user's profile under 'User preferences'. Note that this setting is applied per-user across all devices; if you change the default dashboard on a mobile device, it will also change for that user on their desktop. To maintain different default dashboards for different devices, you must create and use separate user accounts for each device.

  4. Define user and device exceptions for sidebar configurations

    The exceptions feature allows you to create alternative configurations that trigger when specific matchers (user, device, or role) are met. If multiple exceptions match, they are merged from top to bottom.

    By default, an exception creates a completely new configuration. To inherit settings from the main configuration and only override specific options, set extend_from: 'base' within the exception.

    Constraints:

    • You cannot use user and not_user in the same exception.
    • You cannot use device and not_device in the same exception.
    • user and not_user refer to the user's full name, not their username.
    exceptions:
  - user:
    - 'Jim Hawkins'
    - 'Long John Silver'
    extend_from: 'base' # Inherits main config
    title: 'My Home'
    order:
      ... # Custom order for these users

  5. Use partials to reuse code fragments in custom-sidebar templates

    Partials are reusable fragments of code that can be included in JavaScript or Jinja templates using the @partial name instruction. When parsed, the instruction is replaced entirely by the content of the specified partial.

    Key behaviors:

    • Nesting: Partials can be inserted inside other partials.
    • Variable Access: Partials automatically inherit variables defined in js_variables or jinja_variables based on the template type they are inserted into.
    • Re-evaluation: If a partial uses an entity, any template containing that partial will be re-evaluated whenever that entity's state changes. To avoid performance issues, avoid creating 'bloated' partials that reference many unrelated entities.

  6. Localize strings using the user's Home Assistant locale

    Use localize and localizeAsync to translate Home Assistant translation resources based on the locale settings configured in the user's profile.

    Sync vs Async:

    • localize: A synchronous method. Use this if the template is rendered after the system has fully loaded. If called during the initial Home Assistant loading process, it may return an empty string or incorrect formatting because locale settings might not be ready.
    • localizeAsync: An asynchronous method that returns a Promise. This is recommended for templates rendered at the beginning of the loading process to ensure the result is returned only after locale settings are ready.
    // Assuming the current language of Home Assistant is English

// Synchronous: Returns "Remove"
localize('ui.common.remove');

// Synchronous: Returns "Friday"
localize('ui.weekdays.friday');

// Asynchronous: Returns a Promise that resolves to "Remove"
localizeAsync('ui.common.remove').then((result) => {
  console.log(result);
});

// Asynchronous: Returns a Promise that resolves to "Friday"
localizeAsync('ui.weekdays.friday').then((result) => {
  console.log(result);
});

  7. Use extendable configurations to share configuration blocks

    The extendable_configs object allows you to define reusable sets of configuration options. By using the extend_from property, a configuration can import options from one or more extendable configurations.

    Merging Logic:

    • Non-overriding: If a configuration already defines an option, it will not be overridden by the extended configuration ("import what I don't already have").
    • Merging: If both the target and the extended configuration have an order list, the items are merged based on the item identifier. If an item exists in both, properties that are missing in the target but present in the extended config are added to that item.
    • Ordering: When extending from multiple configurations (via a list in extend_from), they are processed in the order they are listed.
    title: 'Custom Title'
extend_from: 'example'
extendable_configs:
  example:
    title: 'My Home'
    subtitle: 'Assistant'
    order:
      - item: 'overview'
        icon: 'mdi:monitor-dashboard'
        order: 0

  8. Dynamically change Custom Sidebar options based on the panel URL

    You can make Custom Sidebar options react to changes in the Home Assistant URL by using JavaScript templates and the special dynamic variable panel_url. Any configuration option that accepts a template can be used to change the sidebar's appearance or behavior whenever the user navigates to a different panel, as the template is re-evaluated on every panel_url change.
    # Example: Changing sidebar background based on the current panel
js_variables:
  background_image: 'https://cdn.jsdelivr.net/gh/basnijholt/lovelace-ios-themes@a37376d918fcfe4785be99910dc9a7200ac37da9/themes/homekit-bg-blue-red.jpg'

sidebar_background: |
  [[[
    if (panel_url.startsWith('/lovelace')) {
      return `center / cover no-repeat fixed url('${background_image}')`;
    }
    if (panel_url.startsWith('/5c53de3b_esphome')) {
      return '#DAD8DA';
    }
    return '#2C2C2E';
  ]]]

  10. Install Custom Sidebar via HACS

    To install Custom Sidebar using HACS (recommended):

    1. Navigate to the HACS dashboard and search for custom-sidebar (or use the My Home Assistant redirect link).
    2. Click the yellow Download button in the bottom-right corner, then confirm Download in the dialog.
    3. Add the plugin bundle URL to your configuration.yaml under frontend.extra_module_url.
    4. Restart Home Assistant.

    Critical Constraints:

    • Use the exact path /hacsfiles/custom-sidebar/custom-sidebar-plugin.js. Do not use paths referencing config or www directories.
    • Ensure you reference custom-sidebar-plugin.js and NOT custom-sidebar.js.
    • This must be configured via extra_module_url in YAML; using Dashboard/Lovelace resources in the GUI is not equivalent.
    frontend:
  extra_module_url:
    - /hacsfiles/custom-sidebar/custom-sidebar-plugin.js

  11. Check Custom Sidebar version compatibility with Home Assistant

    Depending on your Home Assistant version, you must install a specific compatible version of Custom Sidebar:

    • Home Assistant 2026.8.0+: Minimum Custom Sidebar v17.0.0
    • Home Assistant 2026.7.0 to 2026.7.4: Latest compatible v16.1.0
    • Home Assistant 2026.6.0 to 2026.6.4: Latest compatible v15.1.0
    • Home Assistant 2026.5.0 to 2026.5.4: Latest compatible v14.2.0
    • Home Assistant 2026.3.0 to 2026.4.4: Latest compatible v13.1.0
    • Home Assistant 2026.2.0 to 2026.2.3: Latest compatible v12.1.1
    • Home Assistant 2025.5.0 to 2026.1.3: Latest compatible v11.2.0