Select

A common form component for choosing a predefined value in a dropdown menu.

Select a fruit

<ui:listCollection
    items="{
        0: {value: 'apple', label: 'Apple'},
        1: {value: 'banana', label: 'Banana'},
        2: {value: 'cherry', label: 'Cherry'}
    }"
    as="collection" />

<ui:select.root collection="{collection}">
    <ui:select.label>Select a fruit</ui:select.label>
    <ui:select.control class="min-w-48">
        <ui:select.trigger placeholder="Choose a fruit" />
    </ui:select.control>
    <ui:select.content>
        <f:for each="{collection.items}" as="item">
            <ui:select.item item="{item}">
                <ui:select.itemText>{item.label}</ui:select.itemText>
                <ui:select.itemIndicator />
            </ui:select.item>
        </f:for>
    </ui:select.content>
</ui:select.root>

import { mount } from 'fluid-primitives';
import { Select } from 'fluid-primitives/select';

mount('select', ({ props }) => {
	// @ts-expect-error
	const select = new Select(props);
	select.init();
	return select;
});

Features

Support for single and multiple selection
Typeahead to allow focusing items by typing text
Keyboard navigation support including arrow keys, home/end
Supports disabled items and groups
Works with Field component for form integration
Supports custom positioning

Installation

typo3 ui:add select

Read more about installing Components and Primitives.

Examples

Default Value

Set an initial selected value.

Select a fruit

<ui:listCollection
    items="{
        0: {value: 'apple', label: 'Apple'},
        1: {value: 'banana', label: 'Banana'},
        2: {value: 'cherry', label: 'Cherry'}
    }"
    as="collection" />

<ui:select.root collection="{collection}" defaultValue="{0: 'banana'}">
    <ui:select.label>Select a fruit</ui:select.label>
    <ui:select.control class="min-w-48">
        <ui:select.trigger placeholder="Choose a fruit" />
    </ui:select.control>
    <ui:select.content>
        <f:for each="{collection.items}" as="item">
            <ui:select.item item="{item}">
                <ui:select.itemText>{item.label}</ui:select.itemText>
                <ui:select.itemIndicator />
            </ui:select.item>
        </f:for>
    </ui:select.content>
</ui:select.root>

Multiple Selection

Allow selecting multiple items.

Select frameworks

<ui:listCollection
    items="{
        0: {value: 'react', label: 'React'},
        1: {value: 'vue', label: 'Vue'},
        2: {value: 'angular', label: 'Angular'},
        3: {value: 'svelte', label: 'Svelte'}
    }"
    as="collection" />

<ui:select.root collection="{collection}" multiple="{true}">
    <ui:select.label>Select frameworks</ui:select.label>
    <ui:select.control class="min-w-48">
        <ui:select.trigger placeholder="Choose frameworks" />
    </ui:select.control>
    <ui:select.content>
        <f:for each="{collection.items}" as="item">
            <ui:select.item item="{item}">
                <ui:select.itemText>{item.label}</ui:select.itemText>
                <ui:select.itemIndicator />
            </ui:select.item>
        </f:for>
    </ui:select.content>
</ui:select.root>

Disabled Items

Disable specific items in the list.

Select an option

<ui:listCollection
    items="{
        0: {value: 'available', label: 'Available Option'},
        1: {value: 'unavailable', label: 'Unavailable Option', disabled: true},
        2: {value: 'another', label: 'Another Option'}
    }"
    as="collection" />

<ui:select.root collection="{collection}">
    <ui:select.label>Select an option</ui:select.label>
    <ui:select.control class="min-w-48">
        <ui:select.trigger placeholder="Choose an option" />
    </ui:select.control>
    <ui:select.content>
        <f:for each="{collection.items}" as="item">
            <ui:select.item item="{item}">
                <ui:select.itemText>{item.label}</ui:select.itemText>
                <ui:select.itemIndicator />
            </ui:select.item>
        </f:for>
    </ui:select.content>
</ui:select.root>

With Item Groups

Organize items into logical groups.

Select produce

<ui:listCollection
    items="{
        0: {value: 'apple', label: 'Apple', type: 'Fruits'},
        1: {value: 'banana', label: 'Banana', type: 'Fruits'},
        2: {value: 'carrot', label: 'Carrot', type: 'Vegetables'},
        3: {value: 'broccoli', label: 'Broccoli', type: 'Vegetables'}
    }"
    groupByKey="type"
    as="collection" />

<ui:select.root collection="{collection}">
    <ui:select.label>Select produce</ui:select.label>
    <ui:select.control class="min-w-48">
        <ui:select.trigger placeholder="Choose produce" />
    </ui:select.control>
    <ui:select.content>
        <f:for each="{collection.group}" as="group" key="type">
            <ui:select.itemGroup>
                <ui:select.itemGroupLabel>{type}</ui:select.itemGroupLabel>
                <f:for each="{group}" as="item">
                    <ui:select.item item="{item}">
                        <ui:select.itemText>{item.label}</ui:select.itemText>
                        <ui:select.itemIndicator />
                    </ui:select.item>
                </f:for>
            </ui:select.itemGroup>
        </f:for>
    </ui:select.content>
</ui:select.root>

With Form Field

Use with the Field component for form validation.

Country

<ui:listCollection
    items="{
        0: {value: 'us', label: 'United States'},
        1: {value: 'uk', label: 'United Kingdom'},
        2: {value: 'de', label: 'Germany'}
    }"
    as="collection" />

<ui:field.root name="country" required="{true}">
    <ui:select.root collection="{collection}">
        <ui:select.label>Country</ui:select.label>
        <ui:select.control class="min-w-48">
            <ui:select.trigger placeholder="Select your country" />
        </ui:select.control>
        <ui:select.content>
            <f:for each="{collection.items}" as="item">
                <ui:select.item item="{item}">
                    <ui:select.itemText>{item.label}</ui:select.itemText>
                    <ui:select.itemIndicator />
                </ui:select.item>
            </f:for>
        </ui:select.content>
    </ui:select.root>
    <ui:field.error />
</ui:field.root>

Localization

Default clear trigger labels are shipped via XLF and follow the current Site Language. For per-template overrides, pass translated strings through the translations prop. Set clearTriggerLabel to {false} or an empty string to omit the aria-label.

<ui:select.root
    collection="{myCollection}"
    translations="{
        clearTriggerLabel: f:translate(key: 'LLL:EXT:site_package/Resources/Private/Language/locallang.xlf:select.clear')
    }"
>
    ...
</ui:select.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

select.root

Provides shared select state and wraps all related parts. Renders a <div> element.

Name	Description	Required	Default
`collection`	`Domain\Model\ListCollection` The item collection.	Yes	-
`name`	`string` The `name` attribute of the underlying select. Inherited from a surrounding field when available.	No	-
`form`	`string` The associate form of the underlying select.	No	-
`disabled`	`boolean` Whether the select is disabled. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` Whether the select is invalid. Inherited from a surrounding field when available.	No	-
`readOnly`	`boolean` Whether the select is read-only. Inherited from a surrounding field when available.	No	-
`required`	`boolean` Whether the select is required. Inherited from a surrounding field when available.	No	-
`closeOnSelect`	`boolean` Whether the select should close after an item is selected.	No	true
`positioning`	`array` The positioning options of the menu.	No	{ "placement": "bottom-start", "gutter": 8 }
`defaultValue`	`mixed` The initial default value of the select when rendered. Use when you don't need to control the value of the select. Inherited from a surrounding field when available.	No	-
`defaultHighlightedValue`	`string` The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the select.	No	-
`loopFocus`	`boolean` Whether to loop the keyboard navigation through the options.	No	false
`multiple`	`boolean` Whether to allow multiple selection.	No	-
`defaultOpen`	`boolean` Whether the select's open state is controlled by the user.	No	-
`composite`	`boolean` Whether the select is composed with other composite widgets like tabs or combobox.	No	true
`deselectable`	`boolean` Whether the value can be cleared by clicking the selected item.	No	-
`translations`	`array` Localized select labels. Set entries to `` to omit the corresponding `aria-label`. Use `f:translate` for per-template localization overrides when needed.	No	-

select.label

Labels the select. Renders a <label> element.

select.control

Groups the trigger and optional clear button. Renders a <div> element.

select.trigger

Opens and closes the select menu. Renders a <button> element.

select.valueText

Displays the selected value or placeholder text. Renders a <span> element.

Name	Description	Required	Default
`placeholder`	`string` The placeholder text to render when no value is selected.	No	-

select.indicator

Displays a decorative indicator for the trigger. Renders a <span> element.

select.clearTrigger

Clears the current selection. Renders a <button> element.

select.positioner

Positions the floating select content. Renders a <div> element.

select.content

Contains the selectable options. Renders a <div> element.

select.itemGroup

Groups related options together. Renders a <div> element.

select.itemGroupLabel

Labels a group of related options. Renders a <div> element.

select.item

Represents a selectable option. Renders a <div> element.

Name	Description	Required	Default
`item`	`mixed` The item to render.	Yes	-

select.itemText

Displays the text content of an option. Renders a <span> element.

select.itemIndicator

Displays the selected-state indicator for an option. Renders a <div> element.

select.hiddenSelect

Provides the native <select> element for form submission. Renders a <select> element.

Anatomy

<primitives:select.root>
    <primitives:select.label />
    <primitives:select.control>
        <primitives:select.trigger>
            <primitives:select.valueText />
            <primitives:select.indicator />
        </primitives:select.trigger>
        <primitives:select.clearTrigger />
    </primitives:select.control>
    <primitives:select.positioner>
        <primitives:select.content>
            <primitives:select.item>
                <primitives:select.itemText />
                <primitives:select.itemIndicator />
            </primitives:select.item>
            <primitives:select.itemGroup>
                <primitives:select.itemGroupLabel />
            </primitives:select.itemGroup>
        </primitives:select.content>
    </primitives:select.positioner>
    <primitives:select.hiddenSelect />
</primitives:select.root>