Skip to content

Releases: elchininet/custom-sidebar

Release list

v17.1.0

v17.1.0 Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 19 Aug 23:36
v17.1.0
a70c17d

This release is a minor one so it doesn't represent a breaking change. It updates the home-assistant-javascript-templates package to its latest version and refactors the code to support the latest changes in this dependency.

Previously, when custom-sidebar was executed, a WebSocket subscription was created to receive entity changes and be able to re-render the templates using them. This happened even if the configuration didn't contain any JavaScript template. After updating the home-assistant-javascript-templates package, the code has been modified to start the WebSocket subscription only when a JavaScript template that executes variables or methods susceptible to changes is executed. If the configuration doesn't use JavaScript templates or the JavaScript templates don't execute any reactive variable or method, then the WebSocket subscription is not created.

🚀 Features

🧩 Dependencies

  • [Dependencies]: Bump the dependencies-dev group with 4 updates
  • Solve vulnerabilities
  • [Dependencies]: Bump the dependencies-dev group with 2 updates
  • [Dependencies]: Bump js-yaml from 5.2.3 to 5.3.0 in the dependencies-prod group across 1 directory
  • Do not subscribe to WebSocket by default

Contributors

elchininet and dependabot
Assets 4
Loading

v17.0.0

v17.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 05 Aug 17:58
v17.0.0
f0644af

⚠️⚠️⚠️ BREAKING CHANGE! READ BEFORE UPDATE ⚠️⚠️⚠️

This release is a major one and it is a breaking change. This version needs Home Assistant 2026.8.0 as the minimum version to work. So, if you are not already in this version of Home Assistant DO NOT UPDATE.

Fix dialogs functionality

Home Assistant 2026.8.0 has implemented a panel-readiness feature for panels and the ha-panel-config has been set with this option, and this broke the custom-sidebar dialogs functionality. This has been fixed in this release.

Fix default_path option edge case

In certain scenarios (mainly very slow systems or slow network connections), the default_path was not working because its logic could run before the panel got loaded and it could get overridden by the default panel navigation. This has been fixed in this release.

🛠 Fixes

🧩 Dependencies

  • [Dependencies]: Bump typescript-eslint from 8.63.0 to 8.64.0 in the dependencies-dev group
  • Update pnpm to version 11.15.0
  • [Dependencies]: Bump the dependencies-dev group with 2 updates
  • [Dependencies]: Bump js-yaml from 5.2.1 to 5.2.2 in the dependencies-prod group across 1 directory
  • [Dependencies]: Bump the dependencies-dev group with 4 updates
  • [Dependencies]: Bump js-yaml from 5.2.2 to 5.2.3 in the dependencies-prod group across 1 directory
  • Migrate home assistant to version 2026.8.0

⚙️ Configuration

📝 Documentation

Contributors

elchininet and dependabot
Loading

v16.1.0

v16.1.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 18 Jul 14:51
v16.1.0
7b878ed

This is a minor release and it shouldn't represent a breaking change. So, if you are already in version v16.0.0 you can update safely. If you are not already in this version, please, read the release notes of v16.0.0. This release adds two more log messages when the cs_debug parameter is enabled to help debugging issues.

New logs when an item is matched and when an item is skipped if cs_debug parameter is enabled

As you already know, when the cs_debug parameter is enabled (adding the parameter ?cs_debug at the end of the URL), the plugin logs relevant information in the browser's console that could help debug issues as well as it throws errors if a query fails to find an element. From now on, among the useful information that the debug logs provide, you can also find when an item is matched and when an item is skipped.

Let's take as an example this issue. If this feature would existed before, and that user would enabled the cs_debug parameter, they could see the next messages among the other debug messages in the browser's console:

custom-sidebar debug: item "/energy" matched the element with text "Energie Leistung aktuell" and href "/energy-live"

custom-sidebar debug: item "/energy-live" matches with the element with text "Energie Leistung aktuell" and href "/energy-live" but as this element was already matched by "/energy", this matching will be ignored

These message would have helped the user to identify their mistake by themselves.

🚀 Features

🧩 Dependencies

  • [Dependencies]: Bump the dependencies-dev group with 2 updates
  • [Dependencies]: Bump js-yaml from 5.2.0 to 5.2.1 in the dependencies-prod group across 1 directory
  • Solve vulnerabilities through pnpm overrides
  • Multiple config changes

⚙️ Configuration

📝 Documentation

📦 Other

  • Move DOM and subscribers logic to different modules

Contributors

elchininet and dependabot
Loading

v16.0.0

v16.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 01 Jul 20:35
v16.0.0
b080083

⚠️⚠️⚠️ BREAKING CHANGE! READ BEFORE UPDATE ⚠️⚠️⚠️

This release is a major one and it is a breaking change. This version needs Home Assistant 2026.7.0 as the minimum version to work. So, if you are not already in this version of Home Assistant DO NOT UPDATE.

Home Assistant 2026.7.0 migrated more-info toggles to lazy context (pull request 1 and pull request 2), something that broke all the methods to format date and time. In this version there was also a revamp design/gallery to use theming and align with app ui in which the sidebar has been refactored and changed its layout, something that broke all the custom-sidebar options related to the sidebar's items.

This release fixes these issues and custom-sidebar will work again with Home Assistant 2026.7.0.

🛠 Fixes

  • Make custom sidebar compatible with home assistant 2026.7.0

🧩 Dependencies

  • [Dependencies]: Bump the dependencies-dev group with 5 updates
  • [Dependencies]: Bump the dependencies-prod group across 1 directory with 2 updates
  • Make custom sidebar compatible with home assistant 2026.7.0

📝 Documentation

  • Add a note to the Configuration file section in the documentation
  • Move previous Home Assistant versions installation warnings into details
  • Make custom sidebar compatible with home assistant 2026.7.0

Contributors

elchininet and dependabot
Loading

v15.1.0

v15.1.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 21 Jun 21:36
v15.1.0
553836f

This release is a minor one and it should not represent a breaking change for the majority of users. It fixes a bug, brings a new feature and migrates the js-yaml package.

The width main configuration option now allows CSS calc functions

Previously, the width main configuration option allows only numbers and strings to set the values, but the string format needed to be a number followed by one of the allowed units (%, em, ex, px, rem, vh, vmax, vmin, vw). This has been extended, and now on top of the previous formats, it also allows to set a CSS calc function. This will give more flexibility to this option allowing it to use CSS variables.

Fix the width main configuration option set in the hidden property when the sidebar has been set in narrow

This bug only ocurred in a mobile device with a big screen if one collapsed the sidebar in landscape mode and then changed the screen to portrait mode. In those cases, the value set in the hidden property of the width main configuration option was ignored. This has been fixed in this release.

js-yaml package has been migrated to version 5

This should not represent a breaking change for the majority of users, that is why it is being shipped in a minor release instead of a major. But if you find any issue with this version, it should be related to this migration. If you are using YAML 1.1 legacy features, you need to be aware that there are several changes and now the parser uses the recommended CORE_SCHEMA. Check the previous migration guide for more details.

🚀 Features

  • Allow CSS calc functions in the width main configuration option

🛠 Fixes

🧩 Dependencies

  • [Dependencies]: Bump the dependencies-dev group with 3 updates
  • [Dependencies]: Bump js-yaml from 4.1.1 to 4.2.0 in the dependencies-prod group across 1 directory
  • [Dependencies]: Bump the dependencies-dev group with 4 updates
  • [Dependencies]: Bump the dependencies-dev group with 4 updates
  • [Dependencies]: Bump js-yaml from 4.2.0 to 5.0.0 in the dependencies-prod group across 1 directory
  • Solve vulnerabilities through pnpm overrides

⚙️ Configuration

  • [Github Actions]: Bump actions/checkout from 6 to 7 in the actions-deps group across 1 directory

📝 Documentation

  • Allow CSS calc functions in the width main configuration option

📦 Other

  • Move the expanded attributes check to a utility function

Contributors

elchininet and dependabot
Loading

v15.0.0

v15.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 03 Jun 21:48
v15.0.0
c3a194a

⚠️⚠️⚠️ BREAKING CHANGE! READ BEFORE UPDATE ⚠️⚠️⚠️

This release is a major one and it is a breaking change. This version needs Home Assistant 2026.6.0 as the minimum version to work. So, if you are not already in this version of Home Assistant DO NOT UPDATE.

Home Assistant 2026.6.0 has refactored the sidebar's items and this broke custom-sidebar completely. In this release, the necessary changes have been applied to make custom-sidebar work with this version of Home Assistant.

🛠 Fixes

🧩 Dependencies

  • Update docs dependencies and solve vulnerabilities
  • [Dependencies]: Bump the dependencies-dev group with 3 updates

📝 Documentation

📦 Other

Contributors

elchininet and dependabot
Loading

v14.2.0

v14.2.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 22 May 22:01
v14.2.0
cfba09f

This release is a minor one and it doesn't represent a breaking change. It brings new features to the plugin.

Format date and time async methods in JavaScript templates

The JavaScript methods to format dates or time (formatDate, formatDateTime, formatTime and getRelativeTime) use the locale configured by the user. If those methods are called during the first load of Home Assistant, it could be that the locale settings are not loaded yet, hence the result could not follow the locale settings.

For that purpose new async methods have been created. These methods return promises that will be resolved when the locale settings are ready to be used for the formatting.

formatDateAsync

This method formats a date using the Home Assistant locale. It accepts a date, a string ISO 8601 representation of a date or a number representing the timestamp in milliseconds.

// The result of all this examples will be Promises that will resolve to "December 14, 2025"

// Using a date string
formatDateAsync('2025-12-14').then((result) => { /* ... */ });
// Using an ISO 8601 date string
formatDateAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
formatDateAsync(1765715953817).then((result) => { /* ... */ });
// Using a date
formatDateAsync(new Date(2025, 11, 14)).then((result) => { /* ... */ });

formatDateTimeAsync

This method formats a date with time using the Home Assistant locale. It accepts a date, a string ISO 8601 representation of a date or a number representing the timestamp in milliseconds.

// The result of all this examples will be Promises that will resolve to "December 14, 2025 at 12:00 AM"

// Using an ISO 8601 date string
formatDateTimeAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
formatDateTimeAsync(1765666800000).then((result) => { /* ... */ });
// Using a date
formatDateTimeAsync(new Date(2025, 11, 14, 0, 0, 0)).then((result) => { /* ... */ });

formatTimeAsync

This method formats a time using the Home Assistant locale. It accepts a date, a string ISO 8601 representation of a date, a number representing the timestamp in milliseconds, or a string representation of a time in the format HH:MM or HH:MM:SS.

// The result of all this examples will be Promises that will resolve to "12:00 AM"

// Using a time string
formatTimeAsync('00:00').then((result) => { /* ... */ }); // It could also include seconds 00:00:00
// Using an ISO 8601 date string
formatTimeAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
formatTimeAsync(1765666800000).then((result) => { /* ... */ });
// Using a date
formatTimeAsync(new Date(2025, 11, 14, 0, 0, 0)).then((result) => { /* ... */ });

getRelativeTimeAsync

This method gets the relative time of a date using the Home Assistant locale. It accepts a date, a string ISO 8601 representation of a date or a number representing the timestamp in milliseconds. This method also accept a secondary optional boolean parameter to define if the result should be capitalized or not (by default it is false).

// The result of all this examples will be Promises that will resolve to "December 14, 2025"
// Assuming that the current date is December 1st, 2025 at 12:00 AM

// Using an ISO 8601 date string
getRelativeTimeAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
getRelativeTimeAsync(1765666800000).then((result) => { /* ... */ });
// Using a date
getRelativeTimeAsync(new Date(2025, 11, 14, 0, 0, 0)).then((result) => { /* ... */ });

New methods to localize in JavaScript templates

These methods are related to localization/translations using the user locale settings of the user profile.

localize and localizeAsync

These methods localize a Home Assistant translation resource taking into account the current locale settings set in the user's profile.

/ Assuming that the current language of Home Assistant is English

// Returns "Remove"
localize('ui.common.remove');
// Returns "Friday"
localize('ui.weekdays.friday');

// Returns a Promise that resolves to "Remove"
localizeAsync('ui.common.remove').then((result) => { /* ... */ });
// Returns a Promise that resolves to "Friday"
localizeAsync('ui.weekdays.friday').then((result) => { /* ... */ });

New order item property

section_header

Set this property to true to create a section header. Sections headers are intended to create a non-interactive header for a group of items, consisting of just a text and an optional info text. This property can only be set in an item with a property new_item set in true.

Note: An item with the property section_header header in true does not accept properties related to icons, interactivity or hover/selected states.

order:
  - new_item: true
    section_header: true
    item: 'Section Example'
  ...

Remove the text before resolving a promise

When using a promise to set the title or the name order item property, the original text of the element remained there until the promise got resolved with the new text. From now on, this is not the case, the text of the element is removed from the beginning until the promise gets resolved.

🚀 Features

🧩 Dependencies

  • [Dependencies]: Bump the dependencies-dev group with 3 updates
  • [Dependencies]: Bump home-assistant-javascript-templates from 7.0.0 to 7.1.0 (via audit fix) in the dependencies-prod group across 1 directory

📝 Documentation

Contributors

elchininet and dependabot
Loading

v14.1.0

v14.1.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 14 May 23:20
v14.1.0
8417e4b

⚠️⚠️⚠️ POTENTIALLY A BREAKING CHANGE! READ BEFORE UPDATE ⚠️⚠️⚠️

If you don't have custom-sidebar v14.0.0 already installed, read the release notes of v14.0.0 because there are breaking changes in this version.

This is minor release. If you are already in v14.0.0, this is not a breaking change for you. This release brings several improvements in reliability and performance as well as new features.

Refactor the logic to set the sidebar mode

The logic to set the sidebar mode has been refactored to use an event based set up (the same that Home Assistant performs) instead of changing the values in localStorage. This refactors makes the sidebar mode change more reliable and aligned in how it is performed in Home Assistant.

Refactor custom-sidebar code to make it more reliable

In this relase the custom-sidebar logic has been refactored to make it more reliable even in very slow network conditions. Previously, as the plugin was executed immediately after load, it was possible that the plugin failed because Home Assistant was not ready and in a loading state.

At the moment, only the configuration is loaded from the beginning, but the plugin is not executed until Home Assistant is loaded and the DOM is ready to be queried. To achieve this, multiple checks have been placed to detect when the main elements are added or removed from the DOM.

Throw query selector errors when the debug mode is enabled

If a DOM query fails, it is silently ignored and unless the code tries to call some methods or properties in the queried elements, this is not noticed and this is something that makes it harder to debug if someone reports a bug that is provoked by this. From now on, when the debug mode is enabled (adding the cs_debug parameter in the URL) the promises that are set up to query the DOM elements will reject and throw instead of just silently failing. This will make it easier to debug issues with the plugin related to DOM queries.

Added a new method to the JavaScript templates

From now on, a new method will be available in the JavaScript templates to trigger custom events in Home Assistant.

fireEvent

This method allows one to trigger custom events from specific DOM elements. If no element is provided, it will be triggered from the home-assistant element.

// Fire the uix clear_cache option from the document element
fireEvent(
  document,
  'll-custom',
  {
    uix: {
      action: 'clear_cache'
    }
  }
);

// Fire an event from the home-assistant element
// If the element node is not specified, it will be triggered from the home-assistant element
fireEvent(
  'hass-dock-sidebar',
  {
    dock: 'always_hidden'
  }
);

// Fire an event from the home-assistant element without any detail
fireEvent('my-custom-event');

🚀 Features

  • Throw errors when elements are not found in debug mode
  • Add a fireEvent method to JavaScript templates

🧩 Dependencies

⚙️ Configuration

  • Git ignoreDeprecations to the tsconfig of Docusaurus

📝 Documentation

  • Throw errors when elements are not found in debug mode

📦 Other

Contributors

elchininet and dependabot
Loading

v14.0.1

v14.0.1

Choose a tag to compare

View all tags
@github-actions github-actions released this 08 May 23:45
v14.0.1
a9412e1

⚠️⚠️⚠️ POTENTIALLY A BREAKING CHANGE! READ BEFORE UPDATE ⚠️⚠️⚠️

If you don't have custom-sidebar v14.0.0 already installed, read the release notes of v14.0.0 because there are breaking changes in this version.

This is patch release. If you are already in v14.0.0, this is not a breaking change for you. This release fixes a compatibility issue with Safari browsers that could provoke theat the sidebar customisations were not applied in certain circumstances.

🛠 Fixes

Contributors

elchininet
Loading

v14.0.0

v14.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 06 May 19:43
v14.0.0
db07764

⚠️⚠️⚠️ BREAKING CHANGE! READ BEFORE UPDATE ⚠️⚠️⚠️

This release is a major one and it is a breaking change. This version needs Home Assistant 2026.5.0 as the minimum version to work. So, if you are not already in this version of Home Assistant DO NOT UPDATE.

Plugin broken due to sidebar tooltip refactor

Home Assistant 2026.5.0 refactored the sidebar anf how the tooltips are managed and this broke the plugin functionality to add and remove the tooltips. In this version this has been fixed.

Set the dockedSidebar property in the localStorage

This release sets the dockedSidebar entry in the localStore when the plugin starts. As now the sidebar has animations when open and closed, this avoids unwanted animations if the value in localStorage differs from the value set through the sidebar_mode option.

🚀 Features

  • Set the dockedSidebar property in the localStorage

🛠 Fixes

  • Prepare the plugin for the next Home Assistant version (2026.5.0)

🧩 Dependencies

  • Solve vulnerabilities
  • Extend pnpm overrides to solve more vulnerabilities
  • Solve vulnerabilities
  • [Dependencies]: Bump the dependencies-dev group with 5 updates
  • [Dependencies]: Bump the dependencies-prod group across 1 directory with 2 updates
  • Solve vulnerabilities in docs
  • [Dependencies]: Bump the dependencies-dev group with 3 updates
  • [Dependencies]: Bump home-assistant-styles-manager from 4.1.0 to 4.1.2 in the dependencies-prod group across 1 directory
  • [Dependencies]: Bump the dependencies-dev group with 4 updates
  • [Dependencies]: Bump typescript-eslint from 8.58.2 to 8.59.0 in the dependencies-dev group
  • Solve vulnerabilities through pnpm overrides
  • [Dependencies]: Bump the dependencies-dev group with 3 updates

⚙️ Configuration

  • [Github Actions]: Bump LouisBrunner/checks-action from 3.0.0 to 3.1.0 in the actions-deps group across 1 directory
  • [Github Actions]: Bump the actions-deps group across 1 directory with 1 update
  • [Github Actions]: Bump the actions-deps group across 1 directory with 2 updates

Contributors

elchininet and dependabot
Loading