Select
Select components are comboboxes that present a list of options to users for single or multi-selection.
Overview
A select component allows users to choose one or more options from a list of predefined choices. It displays the selected value in a compact input field and reveals a dropdown menu when selected or focused. The select component is ideal for conserving screen space while providing users with multiple options in an organized, accessible format.
Usage
forge-select presents a list of forge-option (optionally grouped with forge-option-group) inside a field frame, and supports label, placeholder, multiple, and showSelectAll. Use it to recommend a default from a closed set of options; reach for a autocomplete instead once a list runs past 10 or so options, or a radio group instead when every option must stay visible for comparison.
Rules
Grouped options
Wrap related forge-option elements in a forge-option-group to label them as a set.
Related options grouped under a labeled forge-option-group.
<forge-select label="Food group" aria-label="Food group">
<forge-option-group label="Produce">
<forge-option value="fruit">
Fruit
</forge-option>
<forge-option value="vegetables">
Vegetables
</forge-option>
</forge-option-group>
<forge-option-group label="Grains">
<forge-option value="bread">
Bread
</forge-option>
<forge-option value="rice">
Rice
</forge-option>
</forge-option-group>
</forge-select>Multiple selection
Set multiple to let a user choose more than one option; selected options render as a comma-separated list in the field.
Multiple lets a user choose more than one option.
<forge-select class="max-w-[256px]" label="Label" aria-label="Label" label-position="inset" label-alignment="default" variant="outlined" theme="default" shape="default" density="default" placeholder support-text-inset multiple select-all-label="Select all" aria-haspopup aria-controls="forge-aria-controls-placeholder">
<forge-option value="1">
Option 1
</forge-option>
<forge-option value="2">
Option 2
</forge-option>
<forge-option value="3">
Option 3
</forge-option>
</forge-select>Select all
Pair multiple with showSelectAll to add a “select all” option above the list — set selectAllLabel to customize its text.
showSelectAll adds a select-all option above a multiple select's list.
<forge-select class="max-w-[256px]" label="Label" aria-label="Label" label-position="inset" label-alignment="default" variant="outlined" theme="default" shape="default" density="default" placeholder support-text-inset multiple show-select-all select-all-label="Select all" aria-haspopup aria-controls="forge-aria-controls-placeholder">
<forge-option value="1">
Option 1
</forge-option>
<forge-option value="2">
Option 2
</forge-option>
<forge-option value="3">
Option 3
</forge-option>
</forge-select>Clicking “select all” fires forge-select-all before the standard change event, with detail.value (every option’s value, or an empty array when deselecting) and detail.isAllSelected. Calling preventDefault() on forge-select-all also suppresses the change event that would otherwise follow it.
selectEl.addEventListener("forge-select-all", (event) => {
if (!userMaySelectAll) {
event.preventDefault();
}
});Label position
Set the field’s label-position to inset (default), block-start, or inline-start to place the label above, before, or floating inside the field.
Above
label-position set to block-start.
<forge-select class="max-w-[256px]" label="Label" aria-label="Label" label-position="block-start" label-alignment="default" variant="outlined" theme="default" shape="default" density="default" placeholder support-text-inset select-all-label="Select all" aria-haspopup aria-controls="forge-aria-controls-placeholder">
<forge-option value="1">
Option 1
</forge-option>
<forge-option value="2">
Option 2
</forge-option>
<forge-option value="3">
Option 3
</forge-option>
</forge-select>Inline
label-position set to inline-start.
<forge-select class="max-w-[256px]" label="Label" aria-label="Label" label-position="inline-start" label-alignment="default" variant="outlined" theme="default" shape="default" density="default" placeholder support-text-inset select-all-label="Select all" aria-haspopup aria-controls="forge-aria-controls-placeholder">
<forge-option value="1">
Option 1
</forge-option>
<forge-option value="2">
Option 2
</forge-option>
<forge-option value="3">
Option 3
</forge-option>
</forge-select>Select dropdown
Attach a forge-select-dropdown to a button trigger instead of a field, for a select-style menu that isn’t tied to a form field’s layout.
A forge-select-dropdown attached to a button trigger instead of a field.
<forge-button variant="outlined" id="select-dropdown-target" aria-haspopup="listbox">
Choose an option
</forge-button>
<forge-select-dropdown target="#select-dropdown-target">
<forge-option value="1">
One
</forge-option>
<forge-option value="2">
Two
</forge-option>
<forge-option value="3">
Three
</forge-option>
</forge-select-dropdown>Select components are comboboxes that present a list of options to users for single or multi-selection.
import "@tylertech/forge/select";| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
label | label | string | — | Controls the label text. |
placeholder | placeholder | string | — | Controls the placeholder text. |
readonly | readonly | boolean | false | Controls whether the select is readonly. |
showSelectAll | show-select-all | boolean | — | Gets/sets whether to show the select all option when in multiple mode. |
selectAllLabel | select-all-label | string | — | Gets/sets the label for the select all option. |
floatLabel | float-label | boolean | false | Whether the label floats above the field. |
density | density | FieldDensity | "default" | The density of the field. |
dense | dense | boolean | false | Whether the field is dense. |
disabled | disabled | boolean | false | Whether the field is disabled. |
required | required | boolean | false | Whether the field is required. |
labelPosition | label-position | FieldLabelPosition | "inset" | The position of the label. |
value | value | any | — | Gets/sets the value. |
selectedIndex | selected-index | number | number[] | — | Gets/sets the selected index. |
options | — | ISelectOption[] | ISelectOptionGroup[] | — | Gets/sets the available options. |
multiple | multiple | boolean | — | Gets/sets the multiple select state. |
open | open | boolean | — | Gets/sets the open state. |
optionBuilder | — | SelectOptionBuilder | — | Gets/sets the option builder function. |
selectedTextBuilder | — | SelectSelectedTextBuilder | — | Gets/sets the selected text builder function. |
beforeValueChange | — | SelectBeforeValueChangeCallback<any> | — | Gets/sets the before value change callback. |
popupClasses | — | string | string[]; - | — | Gets/sets the list of classes to apply to the popup element. |
popupHeaderBuilder | — | ListDropdownHeaderBuilder | — | Gets/sets the callback function for generating header content within the popup. |
popupFooterBuilder | — | ListDropdownFooterBuilder | — | Gets/sets the callback function for generating header content within the popup. |
syncPopupWidth | sync-popup-width | boolean | false | Gets/sets whether the popup width is synchronized with the popup target width. |
optionLimit | option-limit | number | — | Gets/sets the maximum number of options to display in the dropdown. |
observeScroll | observe-scroll | boolean | false | Controls the observation of scroll events on the dropdown. |
observeScrollThreshold | observe-scroll-threshold | number | 0 | The number of pixels from the bottom to trigger the scroll bottom event. Only applicable if `observeScroll` is true. |
constrainPopupWidth | — | boolean | true | Gets/sets whether the popup width will be constrained to a max width of the viewport width (default: `100vw`). |
wrapOptionText | wrap-option-text | boolean | false | Gets/sets whether the options will wrap their text or not. This only applies if `constrainPopupWidth` is `true`, if there is an explicit width set via CSS. |
popoverPlacement | popover-placement | OverlayPlacement | "bottom" | Gets/sets the placement of the popover. |
popoverOffset | popover-offset | IOverlayOffset | — | Gets/sets the offset of the popover. |
popoverFlip | popover-flip | OverlayFlipState | "auto" | Gets/sets the flip state of the popover. |
popoverShift | popover-shift | OverlayShiftState | "auto" | Gets/sets whether the popover should shift to fit within the viewport. |
popoverFallbackPlacements | — | PositionPlacement | null | — | Gets/sets the fallback placements of the popover. |
labelAlignment | label-alignment | FieldLabelAlignment | "default" | The alignment of the label. |
invalid | invalid | boolean | false | Whether the field is invalid. |
optional | optional | boolean | false | Whether the field is optional. |
variant | variant | FieldVariant | "outlined" | The variant of the field. |
theme | theme | FieldTheme | "default" | The theme of the field. |
shape | shape | FieldShape | "default" | The shape of the field. |
popoverIcon | popover-icon | boolean | false | Whether the popover icon is displayed. |
supportTextInset | support-text-inset | FieldSupportTextInset | "none" | The inset of the support text. |
| Name | Type | Description |
|---|---|---|
forge-select-scrolled-bottom | CustomEvent<void> | Dispatched when the dropdown list has scrolled to the bottom. |
change | CustomEvent<any> | Dispatched when the user selects a value. |
forge-select-all | CustomEvent<SelectSelectAllEventData> | Dispatched when the select all option is toggled. |
| Name | Description |
|---|---|
value | The selected text to display |
start | Typically reserved for content/icons that render logically before the default slot content. |
end | Typically reserved content/icons that render logically after the default slot content. |
accessory | Used for content such as a button that is logically connected to the field but should appear distinct from the input. |
support-text | Used for content that provides additional information about the field. Aligns to the inline start of the field. |
support-text-end | Used for content that provides additional information about the field. Aligns to the inline end of the field. |
| Name | Description |
|---|---|
::part(root) | The root container element. |
::part(label) | The label element. |
::part(text-container) | The element container for the selected text. |
::part(text) | The element containing the selected text. |
::part(container) | The container element surrounding the input. |
::part(input) | The element containing te input slot. |
::part(start) | The element containing the start slot. |
::part(end) | The element containing the end slot. |
::part(popover-icon) | The popover icon element. |
::part(accessory) | The element containing the accessory slot. |
::part(support-text) | The support text element. |
::part(support-text) | The element containing the support text slot. |
::part(support-text-end) | The element containing the support text end slot. |
::part(outline) | The element containing the forge-focus-indicator element. |
::part(focus-indicator) | The focus indicator element. |
| Name | Description |
|---|---|
--forge-select-placeholder-color | The color of the placeholder text. |
--forge-field-background | The background of the field surface. |
--forge-field-tonal-background | The background of the field surface in the tonal variant. |
--forge-field-tonal-background-hover | The background of the field surface in the tonal variant on hover. |
--forge-field-filled-background | The background of the field surface in the filled and raised variants. |
--forge-field-outline-style | The style of the field outline. |
--forge-field-outline-width | The width of the field outline. |
--forge-field-shape | The border radius of the field's corners. |
--forge-field-height | The height of the field in its default density. |
--forge-field-inset-height | The height of the field in its default density when the label is inset. |
--forge-field-padding-inline | The inline padding of the field. |
--forge-field-padding-inline-start | The inline start padding of the field. |
--forge-field-padding-inline-end | The inline end padding of the field. |
--forge-field-inner-padding-inline | The padding between elements slotted into the field. |
--forge-field-support-text-margin-block | The margin between the support text and the field. |
--forge-field-support-text-gap | The minimum gap between the support text and the support text end. |
--forge-field-support-text-padding-inline | The inline padding of the support text. |
--forge-field-support-text-padding-inline-start | The inline start padding of the support text. |
--forge-field-support-text-padding-inline-end | The inline end padding of the support text. |
--forge-field-label-margin-inline | The margin between the label and the field when the label is in an inline position. |
--forge-field-label-margin-block | The margin between the label and the field when the label is in the block start position. |
--forge-field-required-padding | The padding between the required indicator and the label. |
--forge-field-required-content | The content of the required indicator. |
--forge-field-optional-padding | The padding between the optional indicator and the label. |
--forge-field-optional-content | The content of the optional indicator. |
--forge-field-multiline-resize | The direction the field can be resized when multiline. |
--forge-field-multiline-min-inline-size | The minimum inline size the field can be resized to when multiline. |
--forge-field-multiline-max-inline-size | The maximum inline size the field can be resized to when multiline. |
--forge-field-multiline-min-block-size | The minimum block size the field can be resized to when multiline. |
--forge-field-multiline-max-block-size | The maximum block size the field can be resized to when multiline. |
--forge-field-popover-icon-transition-duration | The duration of the popover icon animation. |
--forge-field-popover-icon-transition-timing | The timing function of the popover icon animation. |
--forge-field-popover-icon-open-rotation | The rotation of the popover icon when open. |
--forge-field-surface-animation-duration | The duration of background and outline animations. |
--forge-field-surface-animation-timing | The timing function of background and outline animations. |
--forge-field-surface-floating-animation-duration | The duration of the floating label animation. |
--forge-field-surface-floating-animation-timing | The timing function of the floating label animation. |
--forge-field-focus-indicator-width | The width of the focus indicator. |
--forge-field-disabled-opacity | The opacity of the field when disabled. |
--forge-field-disabled-background | The background of the field when disabled. |
| Name | Returns | Description |
|---|---|---|
floatLabelWithoutAnimation(value) | void | Floats the label without an animation. Only applies when the label is inset. |
Keyboard interaction
| Key | Action |
|---|---|
| Space / Arrow up / Arrow down (closed) | Opens the select. The arrow keys also highlight the first option. |
| Escape / Space (open) | Closes the select. |
| Tab / Enter | Selects the focused option and closes the select. If “Select all” is focused, toggles all options. |
| Arrow down / Arrow up | Highlights the next or previous option. |
| Home / End | Highlights the first or last option that isn’t disabled. |
In multiple-select mode, Enter toggles the focused option’s selected state instead of closing the select.
Accessible label
Set the label property to give the select a visible label. forge-select also uses it as the aria-label on the host element (which has role="combobox").
If you need an accessible name that differs from the visible label, or you aren’t showing a label at all, set aria-label or aria-labelledby on forge-select directly. An aria-label you provide is preserved and won’t be overwritten by the label property.