Pick One
import "@taprootio/espalier/pickers/pick-one";
<esp-pick-one>
Component for selecting a single option from a list of options. For selecting multiple options, see esp-pick-some.
Initial state
Set the initially selected item using the selected attribute
on the esp-picker-item:
Variable-height items
Items with longer text wrap naturally. The menu sizes itself to fit the actual content height of each item:
Typeahead (local filtering)
Add the typeahead attribute to let the user type to filter
the option list. The input becomes editable and the picker
switches to a filter icon on focus:
Typeahead (remote filtering)
Set the fetchItems property to a callback that returns
matching items from a server. The picker debounces input
(300 ms by default) and shows a loading indicator while
the request is in flight. Use the provided AbortSignal
to cancel stale requests:
Attributes
<esp-pick-one> has the following attributes:
value
value has a default value of undefined.
The currently selected item value, or undefined when no item
is selected.
Setting this updates the selected state across the canonical picker items and any active filtered menu items.
typeahead
typeahead has a default value of false.
When true, the picker input becomes a typeahead search field. The user types to filter the option list.
debounce-ms
debounce-ms has a default value of undefined.
Debounce delay in milliseconds for typeahead input. Defaults
to 0 for local filtering and 300 for remote fetching.
name
name has a default value of "".
The name used when the picker participates in a <form>.
required
required has a default value of false.
When true, a selection must be made before the form can be submitted.
required-message
required-message has a default value of "".
A custom message to display when the picker is required but no
selection has been made. Defaults to
"Please select an option." for esp-pick-one and
"Please select at least one option." for esp-pick-some
when not set.
disabled
disabled has a default value of false.
When true, the picker is disabled and cannot be interacted with.
pickerItems
pickerItems has a default value of [].
The list of picker items to display in the picker.
It can either be bound programmatically or computed
from the child esp-picker-item elements.
placeholder
placeholder has a default value of "Choose...".
The text that is displayed in the input prompting the user to choose options.
width
width has a default value of "".
An explicit width for the picker trigger. Accepts any valid
CSS width value (e.g. "5em", "80px"). When set, the host
element is sized to this width while the dropdown menu is
allowed to be wider to accommodate longer items.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-pick-one> has the following methods:
focus
Focus the picker.
validate
Re-run constraint validation and dispatch esp-validity-changed.
checkValidity
Check whether the current state is valid (delegates to ElementInternals).
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
Events
<esp-pick-one> emits the following events:
esp-value-changed
esp-value-changed is of type CustomEvent<PickerItem | undefined>.
Fired when the user selects a picker item.
esp-validity-changed
esp-validity-changed is of type CustomEvent<{ valid: boolean; message: string }>.
Fired whenever constraint validation runs.
CSS Properties
<esp-pick-one> has the following CSS properties:
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).