StellarUI

<stellar-listbox>

Properties

Preview

Luna

Whiskers

Mittens

Shadow

Markup

Copy

<stellar-listbox
  label="Favorite kittens"
  description="Select one or more kittens."
  name="kitten"
  multiple
>
  <stellar-listbox-item value="luna" selected>Luna</stellar-listbox-item>
  <stellar-listbox-item value="whiskers">Whiskers</stellar-listbox-item>
  <stellar-listbox-item value="mittens" selected>Mittens</stellar-listbox-item>
  <stellar-listbox-item value="shadow">Shadow</stellar-listbox-item>
</stellar-listbox>

API

Complete props, events, slots, and implementation notes for the shipped listbox.

Props

Prop	Type	Default
`tone`	`neutral \| primary \| secondary \| tertiary \| error`	`neutral`
`size`	`xs \| sm \| md \| lg \| xl`	`md`
`label`	`string`	`''`
`description`	`string`	`''`
`name`	`string`	`''`
`value`	`string`	`''`
`multiple`	`boolean`	`false`
`disabled`	`boolean`	`false`
`readonly`	`boolean`	`false`
`required`	`boolean`	`false`

Events

Event	Source	Notes
`input`	host	Fires whenever selection changes from user interaction.
`change`	host	Fires with each committed user selection change.
`focus`	host	Redispatched when the listbox surface gains focus.
`blur`	host	Redispatched when the listbox surface loses focus.

Slots

Slot	Notes
default	Author one or more direct `stellar-listbox-item` children.
`label`	Optional label content. Overrides `label` when present.
`description`	Optional helper content. Overrides `description` when present.

Notes

The public tag is `stellar-listbox`, matching the shipped listbox controller boundary.
It expects direct `stellar-listbox-item` children and owns selected state, roving focus, and keyboard navigation.
`multiple` toggles between single-select and multi-select behavior, but `value` still remains a single string: the first selected value.
Use `selectedValues`, `selectedItems`, `selectAll()`, and `deselectAll()` for full multi-select state control.
`required`, `aria-invalid`, and `custom-validity` forward to the inner native text input for validation-sensitive flows.
The host exposes `setCustomValidity()`, `checkValidity()`, `reportValidity()`, `validity`, `validationMessage`, and `willValidate`, so app code can use native-like validity APIs on the custom element.
For Datastar, prefer `data-attr:custom-validity="..."` on the custom element host instead of the Pro-only `data-custom-validity` attribute.
The current first pass keeps the architecture aligned with the shipped component contract while using Stellar tokens and field metadata conventions.