Select Input

The select UI component, commonly used in web and application interfaces, is a dropdown menu that allows users to choose one option (or sometimes multiple options) from a predefined list.

Usage

<SelectInput items="$options" label="Number" model="$selectedOption" />
<div>
    You have selected: $selectedOption
</div>

<?php

class FormsExample extends BaseComponent
{
    public array $options = [
        'One',
        'Two',
        'Three',
        'Four',
    ];
    public string $selectedOption = '';
}

Using objects

You can use a list of objects for the items. Use itemTitle property to set up the title field:

<SelectInput 
    items="$items" 
    itemTitle="Name" 
    label="Chose Hero" 
    model="$selectedHero"
/>
<div if="$selectedHero">
    You have selected: {$selectedHero->Name} ({$selectedHero->Id})
</div>

<?php

class FormsExample extends BaseComponent
{
    /**
     * 
     * @var HeroModel[]
     */
    public array $items = [];
    public ?HeroModel $selectedHero = null;

    public function init(): void
    {
        $hero = new HeroModel();
        $hero->Id = 1;
        $hero->Name = 'Superman';        
        $this->items[] = $hero;

        $hero = new HeroModel();
        $hero->Id = 2;
        $hero->Name = 'Batman';
        $this->items[] = $hero;

        $hero = new HeroModel();
        $hero->Id = 3;
        $hero->Name = 'Wonder Woman';
        $this->items[] = $hero;

    }
}

Using associative array

You can use a list of associative objects for the items with associative property. Key of the array item will become your value.

<SelectInput 
    associative 
    items="$itemsAssoc" 
    label="Chose Hero" 
    model="$selectedHeroAssoc"
/>
<div>
    You have selected: $selectedHeroAssoc
</div>

<?php

class FormsExample extends BaseComponent
{
    public array $itemsAssoc = [
        'superman' => 'Superman',
        'batman' => 'Batman',
        'wonder-woman' => 'Wonder Woman'
    ];
    public string $selectedHeroAssoc = '';
}

Allow deselecting

If you want to allow deselecting, you can use nullable property:

<SelectInput 
    items="$items" 
    itemTitle="Name" 
    nullable 
    label="Chose Hero" 
    model="$selectedHero"
/>
<div if="$selectedHero">
    You have selected: {$selectedHero->Name} ({$selectedHero->Id})
</div>

Initial value

If the model already has a value when the component renders, the field shows it instead of the placeholder:

<SelectInput items="$options" label="Number" model="$preselectedOption" />
<div>
    You have selected: $preselectedOption
</div>

<?php

class FormsExample extends BaseComponent
{
    public array $options = [
        'One',
        'Two',
        'Three',
        'Four',
    ];
    public string $preselectedOption = 'Three';
}

Changing the items

The component watches items and model. To update the list, assign a new array to the bound property:

$this->options = [...$this->options, 'Five'];

Keyboard and accessibility

The select works from the keyboard like a native select. You can try it on any example above.

When the list is closed:

• Tab moves the focus to the field.
• ArrowDown, ArrowUp, Enter or Space opens the list on the current value.

When the list is open:

• ArrowDown and ArrowUp move the highlight.
• Home and End jump to the first and the last option.
• Typing a letter jumps to the next option whose title starts with that letter.
• Enter or Space selects the highlighted option.
• Escape closes the list.
• Tab closes the list and moves the focus on.

The focus stays on the field while you move through the options. The field has the combobox role, the list has the listbox role, and the highlighted option is announced to screen readers through aria-activedescendant. A long list scrolls to keep the highlighted option visible.

Properties

model - two-way data binding.

items - required, list of options.

placeholder - (optional), text shown when nothing is selected. With nullable, it is also the title of the empty option. Default: Please select.

label - (optional), label text for the input.

hint - (optional), hint text for the input.

associative - (optional), use associative list for items.

inputClass - (optional), class attribute for the input.

wrapperClass - (optional), class attribute for the wrapper container.

id - (optional), id attribute of the field. Also used to build the ids of the list and its options.

name - (optional), name of the field. Inside an Action Form, validation results are matched by id, then by name.

nullable - (optional), boolean, adds an empty option at the top of the list. Selecting it sets the model to null. Default: false.

itemTitle - (optional), property of the item that should be used as option title.

itemValue - (optional), property of the item that should be used as option value.

isInvalid - (optional), boolean, marks the input as invalid, adds error highlight.

Events

(model) - event that happens when the user selects an option. Receives the new value. model="$prop" binds to it for you.

Slots

default - (optional), default slot, renders after the hint container.