Listbox (Select)

Listboxes are a great foundation for building custom, accessible select menus for your app, complete with robust support for keyboard navigation.

# Basic example

Basic list boxes are created using the x-listbox, x-listbox:options, x-listbox:option and x-listbox:toggle components. And additionally x-listbox:search and x-listbox:text are available

The x-listbox:toggle will automatically open/close the x-listbox:options when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard.

<div x-listbox>
    <button x-listbox:toggle>
        Values:
        <span x-listbox:text></span>
    </button>
    <div x-listbox:options>
        <input x-listbox:search type="text">
        <ul>
            <li x-listbox:option>Account settings</li>
            <li x-listbox:option>Documentation</li>
            <li x-listbox:option>Invite a friend</li>
        </ul>
    </div>
</div>

# Options

Options can be passed as a block or individually using the x-nui directive.

Be sure to change the case type of the option name from "camelCase" to "kebab-case" when passing the options individually.

In block

<div x-nui="{expose:'data'}"></div>

Individually

<div x-nui:expose="data"></div>

# For x-listbox

name	type	default	description
`multiple`	boolean	`false`	It specifies that multiple options can be selected at once.
`minLength`	number	`3`	Minimum length for search box.
`autoClose`	boolean, string	`true`	Configure the auto close behavior of the dropdown: `true` - the dropdown will be closed by clicking outside or inside the dropdown menu. `false` - the dropdown will be closed by clicking the toggle button and manually calling hide or toggle method. `'inside'` - the dropdown will be closed (only) by clicking inside the dropdown menu. `'outside'` - the dropdown will be closed (only) by clicking outside the dropdown menu.
`trigger`	string	`click`	Sets whether the menu should be displayed on `hover` or `click` on the trigger element. Possible values: `hover` or `click`
`position`	string	`bottom-start`	Sets the placement of the dropdown menu. Possible values: `auto`\| `auto-start`\| `auto-end`\| `top`\| `top-start`\| `top-end`\| `bottom`\| `bottom-start`\| `bottom-end`\| `right`\| `right-start`\| `right-end`\| `left`\| `left-start`\| `left-end`
`display`	string	`dynamic`	By default, we use Popper for `dynamic` positioning. Disable this with `static`.
`offset`	string, array, function	`0,2`	Offset of the dropdown relative to its target. You can pass a string in attribute with comma separated values like: `x-nui:offset='10,20'`.
`strategy`	string	`absolute`	Describes the positioning strategy to use. Possible values: `absolute` or `fixed`
`toggleFirstChild`	boolean	`false`	Tells you to toggle the visibility of the first child of the menu.
`expose`	null,string	`null`	Exposes the `component api`. Receives the name of the variable where the component api will be exposed

# For x-listbox:option

Note: only applicable individually

name	type	default	description
`value`	string		Is used to specify the value of the option.
`selected`	string		It specifies that an option should be pre-selected.

# API Component

The component API is an object that contains the following properties:

name	type	description
`main`	element	Element where it is found: `x-listbox`
`toggle`	null,element	Element where it is found: `x-listbox:toggle`
`menu`	null,element	Element where it is found: `x-listbox:options`
`show`	boolean	Determines the visibility of the dropdown menu.
`selected`	element[]	Lists of all selected elements.
`options`	element[]	Lists of the options (elements) found.
`noResult`	boolean	Indicates whether results exist after filtering.

# Class Names

CSS classes that are added to describe a state.

name	description
`open`	Set to `x-listbox:toggle` and `x-listbox:options` when the dropdown menu is visible.
`selected`	Set to `x-listbox:option` when selected.

# Modifiers

# .wrapper

Tells you that the element is a container and that you should toggle the visibility of the first element. It works the same as the toggleFirstChild option. It can only be applied to x-listbox:options.

On this page