Selects
Selects allow users to choose one option from a list. You can use the wire:model directive to bind the selected value to a property.
Selects will automatically flip when the available space is not enough to display the dropdown.
1<x-select id="select-01" placeholder="Select a language">2 @foreach($this->options as $key=>$value)3 <x-option :value="$key">{{ $value }}</x-option>4 @endforeach5</x-select>Multi-Select
Allow users to select multiple options from a list by adding the multiple attribute.
A selection that is too long for the field is cut with an ellipsis — the select keeps its width instead of growing. To show a count instead of the names, use limit.
1<x-select id="select-02" multiple>
2 <x-option value="en" selected>English</x-option>3 <x-option value="de" selected>German</x-option>4 <x-option value="es" selected>Spanish</x-option>5 <x-option value="fr">French</x-option>6</x-select> Limit Multi-Select Text
Limit the number of selected items by adding the limit attribute. You can customize the text by using the limit-text attribute.
1<x-select id="select-457" multiple limit="1" limit-text="You got :count items!">
2 <x-option value="en" selected>English</x-option>3 <x-option value="de" selected>German</x-option>4 <x-option value="es">Spanish</x-option>5 <x-option value="fr">French</x-option>6</x-select> Checkbox
Show checkboxes next to the options by adding the checkbox attribute.
1<x-select id="select-03" checkbox label="Single choice">
2 <x-option value="en">English</x-option> 3 <x-option value="de" selected>German</x-option> 4 5 <x-option value="es" label="Spanish" /> 6 <x-option value="fr" label="French" /> 7</x-select> 8 9<x-select id="select-04" multiple checkbox label="Multiple choice">
10 <x-option value="en">English</x-option>11 <x-option value="de" selected>German</x-option>12 13 <x-option value="es" selected label="Spanish" />14 <x-option value="fr" selected label="French" />15</x-select> Icons
Add icons by using the icon or icon-end attribute on the x-option component.
Example: <x-option icon="user text-primary-400" />
1<x-select id="select-05" label="Select your role">2 <x-option value="1" icon="command-line--micro">Software Engineer</x-option>3 <x-option value="2" icon="user--micro">Product Manager</x-option>4 <x-option value="3" icon="circle-stack--micro">Data Analyst</x-option>5 <x-option value="4" icon="paint-brush--micro">UX Designer</x-option>6</x-select>Show HTML in the Selection
By default, the selected value shows only the text of the option — icons, images and other markup appear in the dropdown only. Add the show-html attribute to keep the markup of the option in the selected value as well.
The hide-in-preview class below needs show-html: without it, the markup is stripped and the hidden elements show up as plain text.
1<x-select id="select-show-html-off" label="Without show-html"> 2 <x-option value="engineer" icon="command-line--micro" selected>Software Engineer</x-option> 3 <x-option value="manager" icon="user--micro">Product Manager</x-option> 4 <x-option value="designer" icon="paint-brush--micro">UX Designer</x-option> 5</x-select> 6 7<x-select id="select-show-html-on" label="With show-html" show-html> 8 <x-option value="engineer" icon="command-line--micro" selected>Software Engineer</x-option> 9 <x-option value="manager" icon="user--micro">Product Manager</x-option>10 <x-option value="designer" icon="paint-brush--micro">UX Designer</x-option>11</x-select>Hide in Preview
Hide elements from the selected display by adding the hide-in-preview class to any element within the <x-slot:label>.
Elements with the hide-in-preview class will only be visible in the dropdown options, not in the selected display.
This is useful for additional information, icons, or descriptions that should only appear when browsing options.
1<x-select id="select-hide-preview" label="Select an option with hidden elements" show-html> 2 <x-option value="1"> 3 <x-slot:label> 4 Option 1 5 <span class="hide-in-preview text-gray-500 text-sm">(Only visible in dropdown)</span> 6 </x-slot:label> 7 </x-option> 8 <x-option value="2"> 9 <x-slot:label>10 Option 211 <small class="hide-in-preview text-blue-500">- Additional info</small>12 </x-slot:label>13 </x-option>14 <x-option value="3">15 <x-slot:label>16 Option 317 <div class="hide-in-preview text-xs text-gray-400 mt-1">This description is only shown in the dropdown</div>18 </x-slot:label>19 </x-option>20</x-select>Images
Add images by using the img slot and adding the common img attributes.
The img-tag has the class ".option-image". You can use this class to style the image.
By default, the aspect ratio of the image will be 1/1.
1<x-select id="select-5231" label="Assign to" multiple show-html placeholder="Choose an user"> 2 <x-option value="1"> 3 <x-slot:img class="radius-circle avatar" src="{{ Vite::image('avatar/01.jpg') }}" alt="Avatar 01"></x-slot:img> 4 Sarah Brown 5 </x-option> 6 <x-option value="2" selected> 7 <x-slot:img class="radius-circle avatar" src="{{ Vite::image('avatar/02.jpg') }}" alt="Avatar 02"></x-slot:img> 8 Frank Smith 9 </x-option>10 <x-option value="3">11 <x-slot:img class="radius-circle avatar" src="{{ Vite::image('avatar/03.jpg') }}" alt="Avatar 03"></x-slot:img>12 David Johnson13 </x-option>14 <x-option value="4">15 <x-slot:img class="radius-circle avatar" src="{{ Vite::image('avatar/04.jpg') }}" alt="Avatar 04"></x-slot:img>16 John Doe17 </x-option>18</x-select>Search
Add a search input to the select by adding the search attribute.
1<x-select id="select-52192" search>2 <x-option value="en">English</x-option>3 <x-option value="de">German</x-option>4 <x-option value="es">Spanish</x-option>5 <x-option value="fr">French</x-option>6</x-select>Option Groups
Place <x-option.group label="…" /> between the options to add a heading. It is not a wrapper: every option after it belongs to the group until the next heading.
Group headings cannot be selected, never show up in the selected value and get no checkbox in checkbox mode. While searching they are hidden, and Enter picks the first real option. For the native <select> of <x-field>, use <optgroup> instead.
1<x-select id="select-groups" search>2 <x-option.group label="Germany" /> 3 <x-option value="berlin">Berlin</x-option>4 <x-option value="nuremberg">Nuremberg</x-option>5 <x-option.group label="Austria" /> 6 <x-option value="vienna">Vienna</x-option>7 <x-option value="graz">Graz</x-option>8</x-select>Sizes
Selects come in the same sizes as text inputs: sm, md, lg and xl. Set them with the size attribute.
The default is input-default-size in config/basic-components.php (md) — the same setting text inputs use.
1<x-select id="select-size-sm" size="sm" placeholder="Small select">
2 <x-option value="en">English</x-option> 3 <x-option value="de">German</x-option> 4</x-select> 5 6<x-select id="select-size-md" size="md" placeholder="Medium select">
7 <x-option value="en">English</x-option> 8 <x-option value="de">German</x-option> 9</x-select> 10 11<x-select id="select-size-lg" size="lg" placeholder="Large select">
12 <x-option value="en">English</x-option>13 <x-option value="de">German</x-option>14</x-select> 15 16<x-select id="select-size-xl" size="xl" placeholder="Extra large select">
17 <x-option value="en">English</x-option>18 <x-option value="de">German</x-option>19</x-select> Arrow
Change the indicator on the right with the arrow attribute: up-down shows a double chevron, up a single chevron that flips while the dropdown is open, and none removes it.
The default comes from select-default-arrow in config/basic-components.php and is up-down.
1<x-select id="select-arrow-up-down" arrow="up-down" placeholder="up-down (default)">
2 <x-option value="en">English</x-option> 3 <x-option value="de">German</x-option> 4</x-select> 5 6<x-select id="select-arrow-up" arrow="up" placeholder="up">
7 <x-option value="en">English</x-option> 8 <x-option value="de">German</x-option> 9</x-select> 10 11<x-select id="select-arrow-none" arrow="none" placeholder="none">
12 <x-option value="en">English</x-option>13 <x-option value="de">German</x-option>14</x-select> Label Addons
Add any content next to the label using the labelAddon slot. It is only rendered when the select has a label.
For plain text, the camel-case attribute labelAddon="…" works too. The kebab-case attribute label-addon="…" is silently ignored.
1<x-select id="select-label-addon" label="Timezone">2 <x-slot:labelAddon> 3 <x-button size="xs" type="link" tabindex="-1">Detect</x-button> 4 </x-slot:labelAddon> 5 <x-option value="berlin">Europe/Berlin</x-option>6 <x-option value="london">Europe/London</x-option>7 <x-option value="new-york">America/New York</x-option>8</x-select>Disabled State
Disable the select to prevent users from interacting with it.
1<x-select id="select-58192" disabled>2 <x-option value="en">English</x-option>3 <x-option value="de" selected>German</x-option>4 <x-option value="es">Spanish</x-option>5 <x-option value="fr">French</x-option>6</x-select>Read-Only State
Add readonly to give the select the same read-only look as the other inputs.
1<x-select id="select-readonly" label="Plan" readonly> 2 <x-option value="free">Free</x-option>3 <x-option value="pro" selected>Pro</x-option>4 <x-option value="team">Team</x-option>5</x-select>Subtle
Add subtle to give the select the same tinted background as subtle text inputs. See Text Inputs for details.
1<x-select id="select-subtle" label="Language" placeholder="Select a language" subtle> 2 <x-option value="en">English</x-option>3 <x-option value="de">German</x-option>4 <x-option value="es">Spanish</x-option>5</x-select>Actions
Add actions to the select by using the actions slot.
1<x-select id="select-52191">2 <x-slot:actions> 3 <x-button type="white" icon="plus--micro">Add Language</x-button> 4 </x-slot:actions> 5 <x-option value="en">English</x-option>6 <x-option value="de">German</x-option>7 <x-option value="es">Spanish</x-option>8 <x-option value="fr">French</x-option>9</x-select>Prepend
Prepend the select to an input by using the prepend slot.
1 2<x-input placeholder="Phone number" id="input-527921" type="tel"> 3 <x-slot:prepend> 4 <x-select id="select-527931" placeholder="+49" arrow="up"> 5 <x-option value="1">+1</x-option> 6 <x-option value="44">+44</x-option> 7 <x-option value="49" selected>+49</x-option> 8 <x-option value="33">+33</x-option> 9 </x-select>10 </x-slot:prepend>11</x-input>Append
Add buttons, icons or text to the end of the select with the append slot — the same addons as on Text Inputs. The select has its own prepend slot as well.
1<x-select id="select-append" placeholder="Assign to">2 <x-slot:append> 3 <x-button icon="user-plus--micro" /> 4 </x-slot:append> 5 <x-option value="sarah">Sarah Brown</x-option>6 <x-option value="frank">Frank Smith</x-option>7 <x-option value="david">David Johnson</x-option>8</x-select>Max Height
Limit the height of the dropdown by adding the max-height attribute. The value of the max-height attribute is in pixel.
1<x-select max-height="200" id="select-max-height" placeholder="Select a language"> 2 <x-option value="en">English</x-option> 3 <x-option value="de">German</x-option> 4 <x-option value="es">Spanish</x-option> 5 <x-option value="fr">French</x-option> 6 <x-option value="it">Italian</x-option> 7 <x-option value="nl">Dutch</x-option> 8 <x-option value="pl">Polish</x-option> 9 <x-option value="pt">Portuguese</x-option>10 <x-option value="ru">Russian</x-option>11</x-select>Dropdown Position and Styling
The dropdown list is rendered directly into <body> and positioned with position: fixed. A parent with overflow: hidden or a modal can no longer clip it, and inside a modal its z-index is raised above the modal.
Clicks and focus changes inside the list stop at the list. They no longer bubble to the page, so they don't trigger the click-outside handling of a surrounding modal or dropdown — or a listener of your own on document.
1// The list is rendered into <body>, so `.bc-select .bc-option` no longer matches2.bc-select-dropdown .bc-option {3 font-size: $fs-sm;4}5 6// One select only: its list has the id "<id>-select-listbox"7#select-language-select-listbox .bc-option.selected {8 color: $color-primary-500;9}Error State
Errors will automatically be added, if you connected a model via wire:model and the model is invalid.
1<x-select id="dropdown-error" wire:model="error_example" label="Error example" wire:loading>2 <x-option value="1">Option 1</x-option>3 <x-option value="2">Option 2</x-option>4 <x-option value="3">Option 3</x-option>5</x-select>Default Select
If you want to have the unstyled default select without our custom wrapper, you can use the x-field component.
1<x-field class="field-select" label="Default Select" hint="Without our wrapper" description="We do not recommend using this, as it will not be styled.">2 <select class="input field-item">3 <option value="1">Option 1</option>4 <option value="2">Option 2</option>5 <option value="3">Option 3</option>6 </select>7</x-field>Component Attributes
All attributes and slots of <x-select>. Anything else — class, x-on:…, data-… — is merged onto the outer <div class="field field-select">.
| Attribute | Type | Default | Description |
|---|---|---|---|
| id | String | Required | Must be unique on the page. The inner parts derive their IDs from it, e.g. the list gets <id>-select-listbox. |
| wire:model | String | — | The property that holds the value. It is entangled live: every change is sent to the server right away. |
| wire:loading | Boolean | — | Shows the loading state with a spinner while a request runs. Narrow it down with wire:target. |
| label | String | — | Label above the select. |
| labelAddon | Slot | — | Content next to the label. Only rendered together with label. |
| hint | String | — | Text between the label and the select. |
| description | String | — | Text below the select. Hidden while an error is shown. |
| placeholder | String | Choose an option | Shown while nothing is selected. The default is translatable. Don't use the character '. |
| multiple | Boolean | false | Allows several options. The value becomes an array. |
| checkbox | Boolean | false | Shows a checkbox in front of every option. |
| limit | Integer | 3 | With multiple: if more options are selected, a count is shown instead of the names. |
| limit-text | String | :count items selected | Text of that count. :count is replaced with the number. Don't use the character '. |
| search | Boolean | false | Adds a search field to the dropdown. It matches the text, the value and an optional tag attribute of the options and shows up to 25 matches. |
| search-placeholder | String | Search | Placeholder of the search field. |
| search-label | String | Search | Accessible label (aria-label) of the search field. |
| show-html | Boolean | false | Keeps the markup of the option (icons, images) in the selected value. |
| size | String | md | sm, md, lg or xl. Default from input-default-size. |
| arrow | String | up-down | up-down, up or none. Default from select-default-arrow. |
| max-height | Integer | — | Maximum height of the dropdown in pixels. Without it, the dropdown uses the available space. |
| disabled | Boolean | false | The dropdown cannot be opened. |
| readonly | Boolean | false | Read-only look. Does not prevent changes. |
| subtle | Boolean | false | Tinted background, like subtle text inputs. |
| prepend, append | Slot | — | Addons before or after the select. |
| actions | Slot | — | Content at the bottom of the dropdown, e.g. buttons. |
| show-errors | Boolean | true | Pass :show-errors="false" to hide the error message. The select still shows its error state. |