Custom Features for Home Assistant Cards

Custom features support three primary interaction types, though availability varies by feature type:

• Tap: Supported by all features (Buttons, Selectors, Sliders, Toggles, etc.).
• Double Tap: Supported by Buttons, Selector options, and Spinbox buttons. Note that defining a non-none double tap action introduces a 200ms delay to single tap actions.
• Hold: Supported by Buttons, Selector options, and Spinbox buttons.

Adjustable Timings

You can customize the trigger thresholds for complex interactions:

• Hold Time: The duration a button must be held before the action triggers (default: 500ms).
• Double Tap Window: The time window to register a double tap before it is treated as a single tap (default: 200ms).
  • Warning: If you increase the Double tap window, ensure you increase Hold time by at least 100ms to prevent conflicts.
• Repeat Delay: The delay between repetitions when a hold action is set to repeat (default: 100ms).

Almost all fields in custom features support Nunjucks templating (a JavaScript engine similar to Home Assistant's Jinja2). You can use templates to dynamically set labels, icons, units, and CSS styles.

Available Variables

• value: The current value of the feature.
• unit: The current unit of the feature.
• hold_secs: Used during momentary repeat or end actions.
• checked: (For toggles) Boolean indicating if the toggle is on or off.
• option: (For dropdowns and selectors) References the specific option being rendered.
• config: References the feature's configuration. Use config.entity or config.attribute to access the entity ID or attribute with rendered templates. Other templated config fields can be accessed using the render function, e.g., {{ render(config.some_field) }}.
• stateObj: Provides access to the parent card's information (entity ID, state, attributes, etc.). The structure follows the Home Assistant HassEntity type.

The custom:service-call feature type allows you to group multiple interactive elements (entries) together. Each entry can be a different feature type (like button or slider) and can be configured to perform Home Assistant actions via tap_action, double_tap_action, hold_action, or momentary actions (momentary_start_action, momentary_end_action).

Key capabilities include:

• Dynamic Labels: Use Jinja2 templates in the label field to display entity states or attributes (e.g., label: '{{ states(config.entity) }}').
• Custom Styling: Use the styles field to apply CSS to the :host element or specific sub-elements like .tooltip, .icon, or .label. You can use CSS variables like --color, --background, and --background-opacity to theme your features.
• Template-driven Actions: Pass template values into action data, such as brightness_pct: '{{ value | int }}' for a slider.
• Momentary Actions: Use momentary_start_action and momentary_end_action for controls like curtains or garage doors that require a press-and-hold behavior.

features:
  - type: custom:service-call
    entries:
      - type: button
        entity_id: light.sunroom_ceiling
        tap_action:
          action: perform-action
          perform_action: light.turn_on
          data:
            entity_id: light.sunroom_ceiling
            color_name: red
      - type: slider
        entity_id: light.sunroom_ceiling
        value_attribute: brightness
        range:
          - 0
          - 100
        tap_action:
          action: perform-action
          perform_action: light.turn_on
          data:
            brightness_pct: '{{ value | int }}'

To use this project:

1. Install via HACS.
2. In a dashboard, create a Tile Card (or any card supporting card features).
3. Click Add feature and select Custom features row.

Custom Features Row: All custom features must be encapsulated within a Custom features row. This container allows you to:

• Add multiple features to a single row.
• Apply overall CSS styles to the row.
• Control feature widths using the flex-basis CSS property.

Adding Features: Inside a row, use the add custom feature button to add individual features. Features can be reordered, copied, edited, or deleted.

Row Styling: CSS styles for the row must be encapsulated in a selector, such as :host:

:host {
  --mdc-icon-size: 32px;
}

Autofill: By default, features autofill with the parent entity's information (state, icon, unit of measurement). Disable this via the Autofill toggle if you need to manually define an entity or value.

Spinboxes create Home Assistant-style number boxes with increment and decrement buttons.

Behavior:

• Users can increment/decrement the internal value using buttons.
• Debounce time: The user-defined tap action fires only after the buttons are no longer pressed for a specified duration (default: 1000ms).
• Update after action delay: Controls how long the spinbox waits before updating its internal value from Home Assistant (similar to sliders).
• Repeat on hold: You can set the hold action to repeat in the Center tab to allow continuous incrementing/decrementing while holding the button.

Best Practices: To prevent excessive Home Assistant calls, use an action that sets a value (e.g., number/input_number.set_value or climate.set_temperature) and use the value template variable to pass the current internal value to the action call. This allows the user to reach the desired value before a single update is sent.

Customizing Buttons: You can override default behavior by changing the tab bar to Increment or Decrement. This converts the feature into a standard button feature and disables the default increment/decrement/debounce logic.

# Conceptual usage for an action
service: input_number.set_value
target:
  entity_id: input_number.target_temp
data:
  value: "{{ value }}"

Both the custom features row and individual features support custom CSS.

Important: You must wrap your styles within a :host selector. You cannot set styles outside of a selector.

:host {
  flex-basis: 200%;
  --color: red;
  --icon-color: blue;
}

Common CSS Classes

Use these classes to target specific sub-elements within a feature:

General Style Properties

These internal CSS attributes can be used within :host or specific classes:

:host {
  flex-basis: 200%;

  --color: red;
  --icon-color: blue;
}

.background {
  background: blue;
}
.icon {
  --mdc-icon-size: 32px;
}
.label {
  color: red;
}
.tooltip {
  --tooltip-label: '{{ (value / 60) | int }}:{{ 0 if (value - 60*((value / 60) | int)) < 10 else "" }}{{ (value - 60*((value / 60) | int) | int }}';
}