Area picker

The area picker is a field for choosing one area: the room a device is in, the area a card shows, the area a helper belongs to. Select the field to open a searchable list of areas. Each area shows its icon, and the floor it is on.

Use the area picker for:

• Choosing exactly one area
• Assigning something to an area, where the area people need might not exist yet

Don't use the area picker for:

• Picking several areas. Use the area selector, which can allow more than one.
• Picking what an action works on. Use the target selector: it accepts areas, but also entities, devices, floors, and labels.
• A field in a form. Use the area selector in a form, and the form renders the picker for you.

1. Field: the button that shows the value and opens the list
2. Label: inside the field, Area by default
3. Value: the icon and name of the area, with its floor below it
4. Clear button: removes the value, when the field is not required
5. Arrow: shows that the field opens a list
6. Helper: optional text below the field
7. List: the popover with a search field and the areas, and at the end the option to add a new area

The label defaults to Area. Set your own when the field needs more context, like Area of the device.

The label shows inside the field. Once people pick an area that is on a floor, the field shows the floor in place of the label, so it reads as the area name with the floor below it. Areas without a floor, like the Garden, keep the label.

At the end of the list, the picker offers to add a new area. When people search for an area that does not exist, that option takes the search as the name: Add new area 'Attic'. Selecting it opens the dialog to create the area, and picks the new area when it is created. In the demos on this page, that dialog does not open.

This option can be turned off.

You can limit the list to areas that have certain entities in them, like only areas with lights:

The filters look at the entities in an area, and the entities of the devices in it. You can also filter on the device class of those entities, leave out entities of some domains, or leave out certain areas.

The picker can show a button instead of an empty field. Once people pick an area, the picker shows it like a regular picker. This fits lists, where people add areas one by one.

• Enabled: selecting the field opens the list, and moves focus to its search field.
• Hover and pressed: the field shows a ripple.
• Focus: the line at the bottom of the field turns 2px thick, in the primary color.
• Search: typing filters the list as you type. When nothing matches, the list says No areas found for your search term. When the home has no areas, it says No areas available.
• Unknown: when the value is an area that does not exist, the field turns to the quiet warning color and shows Unknown area selected.
• Disabled: the field is dimmed to 50% opacity and can't be opened.
• Narrow screens: when the window is at most 870px wide or 500px high, the list opens as a bottom sheet instead of a popover.

Picking an area closes the list. The new value is reported once the list has closed.

The area picker uses the shared picker field and list of the frontend, ha-picker-field and ha-generic-picker.

• Keep the option to add an area where it helps: when people assign something to an area, the area they need might not exist yet.
• Turn the option to add an area off where creating one makes no sense, like in a filter, or when picking from areas that already have something in them.
• Set your own label when Area alone does not say what the area is for.

Focus on the field shows as a thicker bottom line, not as a focus ring. While the list is open as a popover, focus stays inside it. In the list, focus stays in the search field while the arrow keys move the highlight.

The field is at least 56px high and fills the width it gets. The clear button is 32px by 32px.

• The field is announced as a button, named by its label and the area in it. When the picked area is on a floor, the name is the area and floor name.
• The list is announced as a dialog with a list of options, and the picked area as selected.
• The clear button is announced as "Clear", in the language of the user.

• Focus is delegated to a native <button> in the field. Its accessible name is the label together with the text in the field. When the picked area is on a floor, the label is left out.
• The list opens in an element with the role dialog and aria-modal="true", named after the label. The popover traps focus.
• The list has the role listbox, and each area the role option, with aria-selected for the picked area.
• The highlighted row is marked with an active attribute. The list does not set aria-activedescendant.
• The clear button has the translated label ui.common.clear as its accessible name.

• Device picker: pick one device
• Entity picker: pick one entity
• Selector: the area selector, for one or several areas
• Form: renders the picker from a schema

The element is <ha-area-picker>. It reads the areas, floors, devices, entities, and states from the context the app provides, so you don't pass hass to it.

html`
  <ha-area-picker
    .value=${this._areaId}
    .includeDomains=${["light"]}
    @value-changed=${this._areaChanged}
  ></ha-area-picker>
`;

In HTML, the list attributes take JSON:

<ha-area-picker include-domains='["light"]' no-add></ha-area-picker>

• label: the label. Defaults to Area.
• value: the ID of the selected area.
• helper: help text below the field.
• placeholder: the text in the empty field.
• no-add: hides the option to add a new area.
• include-domains: only show areas with entities of these domains.
• exclude-domains: hide areas with entities of these domains.
• include-device-classes: only show areas with entities of these device classes.
• exclude-areas: hide these areas.
• add-button-label: shows a button with this label instead of the empty field.
• required: marks the field as required.
• disabled: disables the picker.

These can only be set from code:

• deviceFilter: a function that gets each device registry entry, and returns true to keep it. Only areas with a matching device show.
• entityFilter: a function that gets the state object of each entity, and returns true to keep it. Only areas with a matching entity show.

• open(): opens the list.

• value-changed: fires when people pick or clear an area. The new area ID is in event.detail.value, or undefined when cleared.
• change: fires after value-changed.

Source: src/components/ha-area-picker.ts