Skip to main content

JavaScript Templates

This templating system IS NOT the same that Home Assistant implements. It is basically a JavaScript code block in which you can use certain client-side objects, variables and methods. To set a property as a JavaScript template block, include the code between three square brackets [[[ JavaScript code ]]]. If you don‘t use the square brackets, the property will be interpreted as a regular string.

tip

Custom Sidebar uses Home Assistant Javascript Templates for the JavaScript templating system. To know all the objects, variables and methods available in the JavaScript templates, consult the proper section in the repository.

If the JavaScript code is used in an option, it will be taken as something that you want to return, but if you have a more complex logic, you can create your own variables and return the desired result at the end.

The entities used in the templates will be stored, so if the state of an stored entity changes, all the templates that use this entity will be reevaluated and rerendered.

JavaScript templates can make use of Reactive JavaScript Variables. If you use a reactive variable in some templates and you modify it in the javascript action of an on_click parameter of an item, all the templates in which the variable was used will be reevaluated in the device in which the action was performed.

On top of all the variables and methods provided by Home Assistant Javascript Templates, the next variables and methods will be available in the templates:

panel_url​

This variable returns the url of the current panel. It will be reevaluated every time that a new panel or a new view is loaded.

info

The next methods will be available in every JavaScript template, but they should not be used in the templates of regular options. They are intended to be used in the javascript action of an on_click property.

openAlertDialog​

This method will open an alert dialog. It accepts only one parameter wich is an object with the next properties: the title and the text of the alert dialog and two optional properties with a confirmText (text of the confirm button) and a confirm action that will be executed when the confirm button is clicked.

<config directory>/www/sidebar-config.yaml
order:
  - new_item: true
    item: 'admin'
    icon: 'mdi:account-key'
    on_click:
      action: 'javascript'
      code: |
        if (user_is_admin) {
          // Execute some code only for admins
        } else {
          openAlertDialog({
            title: 'Error',
            text: 'Only admin users can execute this',
            confirmText: 'Close',
            confirm: () => {
              console.log('The close button was clicked');
            }
          });
        }

openConfirmDialog​

This method will open a confirmation dialog that allow one to accept or decline what it states. It also accepts only one parameter which is an object with the same properties as the openAlertDialog method and on top of them it will also accept a dismissText property to indicate the text of the dismiss button, a destructive property to indicate if the confirmation dialog will execute a destructive action, and a cancel action that will be executed when the dismiss button is clicked.

<config directory>/www/sidebar-config.yaml
order:
  - new_item: true
    item: 'execute'
    icon: 'mdi:script-text-outline'
    on_click:
      action: 'javascript'
      code: |
        openConfirmDialog({
          title: 'Execute the script',
          text: 'Do you want to execute the script?',
          confirm: () => {
            // execute the script
          },
          cancel: () => {
            // do not execute the script
          }
        });

openMoreInfoDialog​

This method will open a more info dialog of the specified entity. It requires an entityId parameter which is the entity that will be open in the more info dialog.

<config directory>/www/sidebar-config.yaml
order:
  - new_item: true
    item: 'Living-room lights'
    icon: 'mdi:lightbulb-group'
    on_click:
      action: 'javascript'
      code: |
        openMoreInfoDialog('light.living_room');

openRestartDialog​

Important

Take into account that even if every user can open the restart dialog, only admin users are authorized to restart Home Assistant.

This method will open the dialog to restart Home Assistant.

<config directory>/www/sidebar-config.yaml
order:
  - new_item: true
    item: 'Restart'
    icon: 'mdi:restart'
    on_click:
      action: 'javascript'
      code: |
        openRestartDialog();

checkConfig​

Important

This method can be executed only by admin users.

This method allows one to validate the Home Assistant configuration. It returns a promise which resolves in an object with a result property. The result property can have two values, valid or invalid. This object will also have two optional properties, errors and warnings that will be filled with the corresponding errors or warnings coming from the Home Assistant configuration check.

<config directory>/www/sidebar-config.yaml
order:
  - new_item: true
    item: 'check config'
    icon: 'mdi:check-circle-outline'
    on_click:
      action: 'javascript'
      code: |
        checkConfig()
          .then((response) => {
            if (response.result === 'valid') {
              openAlertDialog({
                title: 'Configuration valid',
                text: response.warnings
                  ? `The configuration is valid but with warnings: ${response.warnings}`
                  : 'The configuration is valid'
              });
            } else {
              openAlertDialog({
                title: 'Configuration with errors',
                text: response.errors
            });
          }
        });

renderTemplate​

Important

This method can be executed only by admin users.

This method accepts a Jinja template string as a parameter and it will return a promise which resolves in the result of the template.

<config directory>/www/sidebar-config.yaml
order:
  - new_item: true
    item: 'date'
    icon: 'mdi:clock-time-eight'
    on_click:
      action: 'javascript'
      code: |
        renderTemplate(
          "The date is {{ as_timestamp(now()) | timestamp_custom('%Y-%m-%d') }}"
        ).then((result) => {
          openAlertDialog({
            title: 'Date of today',
            text: result
          });
        });

callService​

Important

Some services can be executed only by admin users, for example, restarting Home Assistant.

This method will call a Home Assistant service (renamed some time ago to actions). It allows one to call a service from a JavaScript template. This method needs three parameters, the first one is the domain, the second the type of service and the third an object with the data needed by the service.

<config directory>/www/sidebar-config.yaml
order:
  - new_item: true
    item: 'lights'
    icon: 'mdi:lightbulb-on'
    on_click:
      action: 'javascript'
      code: |
        callService(
          'light',
          'toggle',
          {
            entity_id: user_name === 'Miriam'
              ? 'light.miriam_room'
              : 'light.my_room'
          }
        );

Complex Example​

The next example will create the next things:

  1. Sets the title of the sidebar as "My Home" followed by the current time.
  2. Sets the background of the sidebar red when the panel config is selected and green otherwise.
  3. Adds the number of HACS updates as a notification in the HACS item in the sidebar. In case that there are no updates, an empty string is returned and in these cases the notification will not be displayed.
  4. Creates a new item that redirects to the Home Assistant info page with a dynamic text with the word "Info" followed by the installed Supervisor version between parentheses and the Operating System version in the info text.
  5. Creates a new item that when clicked opens the Home Assistant restart dialog, but if the user is not an admin, then it will open an alert with the title "Error", the text "Non-admin users cannot restart Home Assistant" and the text "Close" in the confirm button.
<config directory>/www/sidebar-config.yaml
title: '[[[ "My Home " + new Date(states("sensor.date_time_iso")).toLocaleTimeString().slice(0, 5) ]]]'
sidebar_background: |
  [[[
    return panel_url === '/config/dashboard'
      ? 'red'
      : 'green';
  ]]]
order:
  - item: hacs
    notification: |
      [[[
        const outdatedHacsEntities = Object.values(entities.update).filter(
          (entity) => entity.platform === 'hacs' && is_state(entity.entity_id, 'on')
        );
        return outdatedHacsEntities.length || '';
      ]]]
  - new_item: true
    item: info
    name: |
      [[[
        return 'Info (' + state_attr('update.home_assistant_supervisor_update', 'latest_version') + ')';
      ]]]
    info: |
      [[[
        return 'OS ' + state_attr('update.home_assistant_operating_system_update', 'latest_version');
      ]]]
    href: '/config/info'
    icon: 'mdi:information-outline'
  - new_item: true
    item: 'restart'
    icon: 'mdi:restart'
    on_click:
      action: 'javascript'
      code: |
        if (user_is_admin) {
          openRestartDialog();
        } else {
          openAlertDialog({
            title: 'Error',
            text: 'Non-admin users cannot restart Home Assistant',
            confirmText: 'Close'
          });
        }