Selector

A selector describes a value: "an entity from the light domain", "a number between 0 and 100", "one of these options". The selector component takes that description and shows the matching control. It is the reason the same kind of value looks the same everywhere in Home Assistant.

The selectors are shared with the rest of Home Assistant:

• Integrations use them for the fields of their actions. The form you get when you add an action to an automation is built from them.
• Blueprints use them for their inputs.
• Integrations can use them in the forms of their config flows and options flows.
• The frontend uses them in its own forms, like the visual editors of dashboard cards.

Use the selector component on its own for:

• Rendering fields one by one, from selectors you get from somewhere else. The frontend does that for the fields of actions, triggers, and conditions, and for blueprint inputs.

Don't use it on its own for:

• A form. Put the selector in the schema of a form, and the form renders it, with labels, helpers, errors, and layout. That is what you need most of the time.

The selector has no parts of its own. It shows one control for the type of the selector, and passes on the label, helper, value, and other settings. That control is often one of the other components on this site, like the entity picker or the switch.

Each selector type is a variant. These are the ones you meet most. Each section says what people see, and what kind of value they give. The options of each type are listed under options per type, in the code section.

For free text, in a text input. It can grow to several lines for longer text, hide what people type for a password, check for an email address or a web address, and show fixed text before or after the value. It can also take a list of values.

For a number. With a range, it shows a slider, with a field next to it to type the exact number. It can also show only the field, which is what it does without a range. A unit and a step size are optional.

For on or off. It shows a switch, with the label next to it.

For one option out of a list. Each option has a value and a label people see.

With fewer than six options, the options show as radio buttons. With six or more, they show in a dropdown. The selector can also be told which of the two to use.

The options can also show as a select box: large tiles, with a description, and optionally an image. Use it for a few options that need explaining.

People can also pick several options. As a list, the options then show as checkboxes. As a dropdown, the picked options show as chips above it. The selector can let people type their own value, and sort the options by label.

For an entity. It shows the entity picker. It can offer only the entities that fit, by their domain, device class, integration, supported features, or unit. People can pick one entity, or several.

For a device. It shows the device picker. It can filter on the device itself, like its integration or manufacturer, or only offer devices with matching entities. People can pick one device, or several.

For an area. It shows the area picker. Like the device selector, it can filter on the entities and devices in an area. People can pick one area, or several.

For a floor, or a label. They work like the area selector, though the label selector has no filters.

For what an action works on. People can add entities, devices, areas, floors, and labels, in any mix, and the action applies to all of them. What can be added can be filtered, like the entity and device selectors.

For a time of day, a date, or both. The time selector shows seconds, unless they are turned off.

For an amount of time, like a delay or a transition. It shows hours, minutes, and seconds. Days and milliseconds can be added, and the seconds left out.

A duration can also be negative, like an offset to sunset in the sun condition. In the offset version, people first choose No offset, Before, or After, and then enter the duration.

For a color temperature, as a slider with the color of the light behind it, in kelvin or in mireds.

The RGB color selector is for a color, picked with the color picker of the browser.

For the color of something on a dashboard, use the theme color selector instead. It offers the colors of the theme by name, so the color follows the theme.

For an icon, with a searchable list of all icons. It can show the icon that is used when people pick none.

For a state of an entity, like heat for a thermostat. The selector offers the possible states of one entity, with their translated names. In a form, that entity often comes from another field.

Some selectors need more of Home Assistant than the demos on this page have. The location selector shows a map. The template and object selectors are code editors, and an object selector with fields is a list of small forms. The action, condition, and trigger selectors show the full automation editor for their part. The media selector browses media from your media players.

There are more than sixty selector types in all. The full list is under all selector types, in the code section.

• Changes: when people change the value, the selector reports the new value. Its shape depends on the type.
• Required: a selector is required unless it is marked optional. A required selector without a check of its own is not valid when it is empty.
• Disabled: a disabled selector disables its control.
• Older selectors: older names and filter options are converted to the current form before the control shows.

The states of each control, like hover, focus, and errors, are those of the component it renders.

The selector draws nothing of its own, so it has no sizes, spacing, or colors. Each type looks like the component it shows: see the specs of the text input, switch, slider, select box, and the pickers for entities, devices, and areas.

Pick the most specific selector for the value. An entity ID is text, but the entity selector gives people a searchable list, with names and icons, and only offers entities that fit. The more specific the selector, the less people have to type, and the fewer mistakes they can make.

• Show the options of a select as a select box for a few options that need explaining.
• Use the target selector for actions, so people can say "all lights in the living room" instead of picking each light. To pick one specific entity, use the entity selector.

The selector adds nothing of its own. Keyboard support, focus, and what a screen reader announces come from the control it shows: see the page of each component, like the entity picker, switch, or slider.

ha-selector adds no role, label, or keys of its own. Calling focus() on it focuses the control it renders.

• Form: renders selectors from a schema
• Entity picker, device picker, and area picker: the controls behind the entity, device, and area selectors
• Select box: the box mode of the select selector
• Selectors documentation: all options, as integrations and blueprints use them

The element is <ha-selector>. The selector and most values can only be set from code, as properties.

html`
  <ha-selector
    .hass=${this.hass}
    .selector=${{ number: { min: 0, max: 100, unit_of_measurement: "%" } }}
    .value=${this._brightness}
    .label=${"Brightness"}
    .required=${false}
    @value-changed=${this._brightnessChanged}
  ></ha-selector>
`;

In HTML on this site, the properties go in data-props, as JSON:

<ha-selector label="Brightness" data-props='{"selector": {"number": {"min": 0, "max": 100}}, "value": 70}'></ha-selector>

In YAML, a selector is a key with the type, and the options below it:

brightness:
  selector:
    number:
      min: 0
      max: 100
      unit_of_measurement: "%"

In the frontend, it is the same, as an object:

{ number: { min: 0, max: 100, unit_of_measurement: "%" } }

For all options of each selector, as integrations and blueprints use them, see the selectors documentation.

The options most used, per type. The selectors documentation on home-assistant.io has all of them.

• text: multiline for longer text, type for another input type like password, email, or url, prefix and suffix for text around the value, and multiple for a list. The value is a string, or a list of strings.
• number: min, max, step, and unit_of_measurement. mode is slider or box. Without a range, it is a box. The value is a number.
• boolean: no options. The value is true or false.
• select: options, as strings or objects with a value and a label. mode is list, dropdown, or box. Without a mode, fewer than six options are a list. multiple, custom_value, and sort. The value is the value of the picked option, or a list with multiple.
• entity: filter, on domain, device_class, integration, supported_features, or unit_of_measurement, and multiple. The value is an entity ID, or a list of entity IDs.
• device: filter, on the device itself, like its integration or manufacturer, entity, to only offer devices with matching entities, and multiple. The value is a device ID, or a list of device IDs.
• area and floor: entity and device, to only offer the ones with matching entities or devices, and multiple. label: only multiple. The value is an ID, or a list of IDs.
• target: entity and device, to filter what can be added. The value is an object with an entity_id, device_id, area_id, floor_id, and label_id, each an ID or a list of IDs, and only the ones in use.
• time: no_second hides the seconds. The value is a string like 07:30:00. A date gives 2026-12-24, and a datetime gives 2026-12-24 07:30:00.
• duration: enable_day, enable_millisecond, and enable_second (set it to false to drop the seconds). mode set to signed allows a negative duration, and mode set to offset asks for No offset, Before, or After first. The value is an object with hours, minutes, and seconds, and days and milliseconds when enabled.
• color_temp: unit set to kelvin, and the range with min and max. Without a unit, it works in mireds. The value is a number.
• color_rgb: no options. The value is a list of the red, green, and blue values, from 0 to 255.
• ui_color: the colors of the theme, by name.
• icon: placeholder, the icon that is used when people pick none. The value is the icon name, like mdi:sofa.
• state: entity_id, the entity whose states it offers. In a form, the entity often comes from another field, through context. The value is the state.

The frontend knows these selector types:

• action: a list of actions, like in a script.
• addon: an app. Older name of the app selector.
• app: an app.
• area: an area.
• areas_display: the order of areas, and which are hidden.
• assist_pipeline: an Assist pipeline.
• attribute: an attribute of an entity.
• automation_behavior: how an automation handles several triggers or conditions.
• backup_location: a location to store backups.
• boolean: on or off.
• button_toggle: one option out of a few, as a row of buttons.
• choose: lets people choose between several selectors, like a number or an entity.
• color_rgb: a color, as red, green, and blue.
• color_temp: a color temperature.
• condition: a list of conditions.
• config_entry: an integration entry.
• constant: a fixed value, shown as text.
• conversation_agent: a conversation agent.
• country: a country.
• date: a date.
• datetime: a date and a time.
• device: a device.
• device_class: a device class of a domain.
• duration: an amount of time.
• entity: an entity.
• entity_name: how the name of an entity is shown on a dashboard.
• file: a file to upload.
• floor: a floor.
• icon: an icon.
• label: a label.
• language: a language.
• location: a place on a map, optionally with a radius.
• media: a media item, from the media browser.
• navigation: a path in Home Assistant, like a dashboard view.
• number: a number.
• numeric_threshold: a threshold, like above or below a number or the state of an entity.
• object: any data, as YAML, or a list of items with fixed fields.
• period: a period of time, like today or this week.
• qr_code: shows a QR code. It does not take input.
• select: one or more options from a list.
• selector: a selector, for editors that build selectors themselves, like the blueprint editor.
• serial_port: a serial port, like a USB stick.
• state: a state of an entity.
• state_class: a state class of a sensor.
• statistic: a statistic.
• stt: a speech-to-text engine.
• target: entities, devices, areas, floors, and labels for an action.
• template: a template, in a code editor.
• text: text.
• theme: a theme.
• time: a time of day.
• timezone: a time zone.
• trigger: a list of triggers.
• tts: a text-to-speech engine.
• tts_voice: a voice of a text-to-speech engine.
• ui_action: what happens when people tap a card.
• ui_clock_date_format: the date format of a clock card.
• ui_color: a color of the theme.
• ui_state_content: what a card shows as the state of an entity.
• ui_time_format: a time format.
• unit_of_measurement: a unit of measurement.

The selectors that start with ui_ are made for the editors of dashboard cards.

These can only be set from code:

• selector: the selector. Required.
• hass: the Home Assistant object. Most selectors need it.
• context: values from elsewhere that some selectors use, like the entity for the state selector. ha-form fills this from the context of a field.
• localizeValue: a function that gets a translation key, and returns the text. Selectors with a translation_key use it for the labels of their options.

• value: the value. Use the property for anything that is not a string.
• label: the label.
• helper: help text, below the control.
• placeholder: the value to show when there is none. ha-form sets it to the default of a field.
• name: the name of the field.
• required: marks the field as required. Note: this is true by default. Set the property to false for optional fields.
• disabled: disables the control.
• narrow: tells the control it is on a narrow screen.

• reportValidity(): checks the value, and returns true when it is valid.
• focus(): focuses the control.

• value-changed: fires when people change the value. The new value is in event.detail.value. Its shape depends on the selector type.

Source: src/components/ha-selector/ha-selector.ts. The selector types are in src/data/selector.ts, and each type has its own component in src/components/ha-selector/.