Combobox

A multi-select component with support for tagging and searching.

<c-ui.combobox
    name="skills"
    placeholder="Select skills"
    :options="['Python', 'Django', 'JavaScript', 'Alpine.js', 'Tailwind CSS']"
/>

{% cotton ui.combobox
    name="skills"
    placeholder="Select skills"
    :options="['Python', 'Django', 'JavaScript', 'Alpine.js', 'Tailwind CSS']"
/%}

Max Tags

Limit the number of items that can be selected.

<c-ui.combobox
        name="top_3"
        placeholder="Select up to 3 items"
        :options="['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5']"
        :max_tags="3"
    />

{% cotton ui.combobox
        name="top_3"
        placeholder="Select up to 3 items"
        :options="['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5']"
        :max_tags="3"
    /%}

Searchable

Enable searching through options.

<c-ui.combobox
        name="countries"
        placeholder="Search countries..."
        :options="['United States', 'United Kingdom', 'Canada', 'Australia', 'Germany', 'France', 'Japan']"
        searchable
    />

{% cotton ui.combobox
        name="countries"
        placeholder="Search countries..."
        :options="['United States', 'United Kingdom', 'Canada', 'Australia', 'Germany', 'France', 'Japan']"
        searchable
    /%}

Writable (Custom Tags)

Allow users to enter custom values not in the list.

<c-ui.combobox
    name="tags"
    placeholder="Type and press Enter to add tags"
    :options="['News', 'Updates', 'Alerts']"
    writable
/>

{% cotton ui.combobox
    name="tags"
    placeholder="Type and press Enter to add tags"
    :options="['News', 'Updates', 'Alerts']"
    writable
/%}

Single Select

Restrict selection to a single item by setting max_tags=1. This behaves like a select but with the tag UI.

<c-ui.combobox
    name="favorite_color"
    placeholder="Pick one color"
    :options="['Red', 'Green', 'Blue', 'Yellow']"
    :max_tags="1"
/>

{% cotton ui.combobox
    name="favorite_color"
    placeholder="Pick one color"
    :options="['Red', 'Green', 'Blue', 'Yellow']"
    :max_tags="1"
/%}

Autoclose

Automatically close the dropdown when the maximum number of tags is reached. This is useful when combined with max_tags to provide a smoother user experience - once the user has selected all allowed items, the dropdown closes automatically.

<c-ui.combobox
    name="top_skills"
    placeholder="Pick your top 2 skills"
    :options="['Python', 'Django', 'JavaScript', 'Alpine.js', 'Tailwind CSS', 'TypeScript']"
    :max_tags="2"
    autoclose
/>

{% cotton ui.combobox
    name="top_skills"
    placeholder="Pick your top 2 skills"
    :options="['Python', 'Django', 'JavaScript', 'Alpine.js', 'Tailwind CSS', 'TypeScript']"
    :max_tags="2"
    autoclose
/%}

Disabled

Prevent interaction with the combobox.

<c-ui.combobox
    name="disabled_example"
    placeholder="Cannot select"
    :options="['One', 'Two']"
    :selected="['One']"
    disabled
/>

{% cotton ui.combobox
    name="disabled_example"
    placeholder="Cannot select"
    :options="['One', 'Two']"
    :selected="['One']"
    disabled
/%}

Responsive positioning

The options panel flips above the field when there isn't room below, keeping it in view. Drag the handle to shorten the viewport and watch it flip.

As a field

Give it any field attribute (label, description, error or badge) and the combobox wraps itself in a Field component, giving you the label, helper text and error styling with no extra markup.

Skills

Pick all that apply.

<c-ui.combobox
    name="skills"
    label="Skills"
    placeholder="Select skills"
    description="Pick all that apply."
    :options="['Python', 'Django', 'JavaScript', 'Alpine.js']"
/>

{% cotton ui.combobox
    name="skills"
    label="Skills"
    placeholder="Select skills"
    description="Pick all that apply."
    :options="['Python', 'Django', 'JavaScript', 'Alpine.js']"
/%}

API Reference

Props

Name	Description	Type	Options	Default
`name`	Form input name.	str	—
`:options`	List of string options to select from.	list	—	[]
`:selected`	List of initially selected values.	list	—	[]
`placeholder`	Placeholder text.	str	—
`:max_tags`	Maximum number of items selectable. -1 for unlimited.	int	—	-1
`:writable`	Allow users to add custom values not in the options list.	bool	`TrueFalse`	False
`:searchable`	Enable searching through the dropdown options.	bool	`TrueFalse`	False
`:close_after_selecting`	Close the dropdown automatically after selecting an item.	bool	`TrueFalse`	False
`:autoclose`	Automatically close the dropdown when the maximum number of tags is reached.	bool	`TrueFalse`	False
`:disabled`	Disable the component.	bool	`TrueFalse`	False
`size`	Size variant from xs to 2xl.	str	`xssmmdlgxl2xl`	md
`:required`	Mark the field as required.	bool	`TrueFalse`	False
`label`	Shorthand: wraps with a label field.	str	—
`description`	Shorthand: adds description text.	str	—
`badge`	Shorthand: badge text on the label (e.g. 'Required').	str	—
`error`	Shorthand: displays error message.	str	—