Describing Variables

Describing Variables

A template can say what each of its variables is, not just what it defaults to. Do that, and every card using the template gets a real control for it — an entity picker, a dropdown, an icon picker — instead of a box of hand-typed YAML.

Describing variables is entirely optional. A template that describes nothing works exactly as it always has.

---

Declaring them

variables: on the template is a list, one entry per variable:

type: custom:decluttering-template-plus
template: room_tile
description: A tile for one room's light.
variables:
  - name: entity
    label: Light
    description: Which entity this tile shows
    selector:
      entity:
        domain: light
  - name: colour
    label: Colour
    selector:
      select:
        options: [red, blue, amber]
    default: red
card:
  type: tile
  entity: '[[entity]]'
  name: [[label]] ([[colour]])'

Key	Type	Required	Description
name	string	✅	The variable's name, as written in [[name]]
label	string	—	What the editor calls it. Defaults to the name
description	string	—	Helper text under the control
selector	mapping	—	Any Home Assistant selector. Defaults to a plain text box
default	any	—	The value to use when a card does not set one

description: on the template itself is shown above the controls, so whoever uses it can see what it is for. It travels with the template when you share it.

An entry with no name, or a name that repeats an earlier one, is ignored rather than breaking the card.

Selectors worth knowing

Any Home Assistant selector works. These are the ones that come up most:

selector: {entity: {}}                                  # any entity
selector: {entity: {domain: light}}                     # lights only
selector: {text: {}}                                    # a line of text
selector: {text: {multiline: true}}                     # a block of text
selector: {number: {min: 1, max: 12, mode: box}}        # a number
selector: {boolean: {}}                                 # a switch
selector: {icon: {}}                                    # an icon picker
selector: {select: {options: [red, blue]}}              # a fixed set
selector: {area: {}}                                    # an area
selector: {ui_color: {}}                                # a Home Assistant colour

A selector that produces a number gives you a real number, so it works as a whole value — see value types.

---

Which value wins

Three places can supply a value. They are tried in this order:

Order	Where	Beats
1	variables: on the card using the template	everything
2	default: inside a declaration	the default: list
3	default: on the template	—

default: is untouched by any of this and still works on its own. You can use both — but if the same name has a default in both places, the declaration is the one that counts, and the template editor says so.

---

What you get in the editor

For a template that declares its variables, the card editor shows:

• the template's description, above everything
• one control per declaration, with its label and helper text
• an Other variables box underneath, holding anything the template does not describe

Nothing is lost either way. Values the template never declared stay editable in that box, and a template that declares nothing shows the plain YAML box exactly as before.

Leaving a control empty sets nothing, so the template's own default applies. That is why a variable with a default shows an empty control rather than the default value — writing it into every card is the duplication templates exist to remove. To set a variable to an actual empty string, use the Other variables box.

---

Warnings

Once a template describes itself, both editors can point out the two mistakes that are easy to make and impossible to see:

Where	Message	Means
Card editor	This template uses variables with no value and no default: …	The card will render the literal text [[name]]
Card editor	This variable is set here but never used by the template: …	Usually a typo in the name, or a leftover from an older version of the template
Template editor	This variable is declared but never used in the template: …	A declaration with no matching [[name]]
Template editor	These variables have a default in both places…	The same name defaulted in variables: and in default:

None of them stop you saving. A template can be edited after the cards that use it, so a card that looks wrong now may be right again in a moment.

A variable used only through a transform counts as used: [[room|slug]] is a use of room.

A placeholder that only appears inside the value of a variable nothing refers to is never substituted, so it is not reported as missing either.

---

Letting the editor write them for you

If you already have the card, you do not have to declare anything by hand — the template editor can work it out. See Turning a card into a template.

---

Next

→ Variables for placeholders, defaults and value types → Visual Editors for the editors themselves → Repeating a Template for rendering one template many times