Select

• Introduction
• Basic Usage
• Options
  • Via Attribute
  • Via Default Slot
  • Via The Append Slot
  • Combining Methods
• Multiple Select
• Opt Groups
• Addons
• API Reference
  • props
  • slots
  • config

#Introduction

The select component offers an easy way to provide select menus in your forms. By simply setting the name attribute it also automatically defines your id and makes sure old values are respected.

#Basic Usage

The most basic usage of the component involves setting a name attribute:

<x-select name="state" />

Of course, the id attribute can easily be overridden:

<x-select name="state" id="state_id" />

#Options

There are multiple ways to provide options to the component. The primary way is to provide an array of options as key/value pairs. This will allow the select component to automatically determine which option should be selected (as long as you're not using wire:model) for you.

#Via Attribute

<x-select name="state" :options="['al' => 'Alabama', 'wi' => 'Wisconsin']" />

You can also provide more complex arrays for the options too.

<x-select
    name="user"
    :options="[
        ['id' => 1, 'name' => 'User 1'],
        ['id' => 2, 'name' => 'User 2'],
    ]"
>
</x-select>

This will set each option's value to the id, and the text of the option to the name. You can of course customize these fields for each select with the valueField and labelField attributes:

<x-select
    name="user"
    :options="[
        ['value' => 1, 'text' => 'User 1'],
        ['value' => 2, 'text' => 'User 2'],
    ]"
    value-field="value"
    label-field="text"
>
</x-select>

You are also able to pass in an array of Eloquent Models to the select as well:

<x-select name="user" :options="\App\Models\User::all()" />

#Via Default Slot

Another way to provide options is to use the default slot on the component:

<x-select name="state">
    <option value="al" @selected($component->isSelected('al'))>Alabama</option>
    <option value="wi" @selected($component->
        isSelected('wi'))>Wisconsin
    </option>
</x-select>

{note} When using the default slot, the select component will not be able to determine if the options in the slot are selected or not automatically for you. You may use the isSelected method on the component though for convenience.

#Via The Append Slot

You can also use the append slot if you are passing in options via the options attribute, and it will add your slotted options after the passed in options:

<x-select name="state" :options="['ny' => 'New York']">
    <x-slot:append>
        <option value="al">Alabama</option>
        <option value="wi">Wisconsin</option>
    </x-slot:append>
</x-select>

#Combining Methods

You can also pass in options using multiple methods. For example, if you pass options in using the options attribute, and also via the default slot, your slotted options will be rendered before the passed in options:

<x-select name="state" :options="['ny' => 'New York']">
    <option value="al">Alabama</option>
    <option value="wi">Wisconsin</option>
</x-select>

#Multiple Select

You can easily create a multiple select by setting multiple to true:

<x-select
    name="state"
    :options="['al' => 'Alabama', 'wi' => 'Wisconsin']"
    multiple
/>

#Opt Groups

The select component can automatically render options as an <optgroup> for you without you needing to manually render the options yourself. The component will check for a children property on the option (name of property is configurable). If it is present, and is not an empty array, the component will render the parent option as an <optgroup>, and then loop through each of the children and render them as normal options.

{note} The children options should have the same property structure as the parent option does.

#Addons

The select component supports most of the available addons this package offers. Header over to the Addons documentation for an in-depth guide on how to use them.

#API Reference

#props

prop	description
name	Name of the select
id	Id of the select. Defaults to name.
value	Value of the select. Gets omitted if wire:model or x-model is present
containerClass	Defines a CSS class to apply to the container of the select
size	Define a size for the select. Default size is md
showErrors	If a validation error is present for the select, it will show the error state on the input
extraAttributes	Pass an array of HTML attributes to render on the select
leadingAddon	Render text on the left of the select
leadingIcon	Render an icon on the left of the select
inlineAddon	Render text inside the input on the select
trailingAddon	Render text on the right of the select
trailingInlineAddon	Render text inside the input on the select
trailingIcon	Render an icon on the right of the select
multiple	Allow muti-select mode
options	An array or Collection of options to render
valueField	Property on an option to use for the value
labelField	Property on an option to use for the text
disabledField	Property on an option to use to determine if it is disabled
childrenField	Property on an option to determine if it has children. Will render as an <optgroup> if children is present and not empty

#slots

slot	description
append	Render options after passed in options have been rendered
before	Render HTML before the select and/or leading addons
after	Render HTML after the select and/or trailing addons
leadingAddon	Render text on the left of the select
leadingIcon	Render an icon on the left of the select
inlineAddon	Render text inside the select on the left
trailingAddon	Render text on the right of the select
trailingInlineAddon	Render text inside the select on the right
trailingIcon	Render an icon on the right of the select

#config

The following configuration keys and values can be adjusted for common default behavior you may want for the select element.

'defaults' => [
    'global' => [
        // Show error states by default.
        'show_errors' => true,

        // Set the fields to use by default for properties on options in select components.
        'value_field' => 'id',
        'label_field' => 'name',
        'disabled_field' => 'disabled',
        'children_field' => 'children',
    ],

    'input' => [
        // Supported: 'sm', 'md', 'lg'
        // Applies to all input types except for checkbox/radios and custom select.
        'size' => 'md',

        // Classes applied by default to input parent div.
        // Will also apply to select.
        'container_class' => null,
    ],

    'select' => [
        // Automatically apply a CSS class to each select.
        'input_class' => null,
    ],
],