Skip to content

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
Assets 4
Loading