Select

The Select input component uses HTML's native select input. Select inputs can be single value selections, or multi-value selections by using the multiple attribute. Use it with the Field component to access all the functionalities.

Examples

Base

Show code

HTML

<section>
    <o-field label="Required">
        <o-select placeholder="Select a name" required>
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
            <option value="vane">Vane</option>
            <option value="billy">Billy</option>
        </o-select>
    </o-field>

    <o-field label="Rounded">
        <o-select placeholder="Select a character" rounded>
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
            <option value="vane">Vane</option>
            <option value="billy">Billy</option>
        </o-select>
    </o-field>

    <o-field
        label="Error"
        variant="danger"
        message="Something went wrong with this field">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
            <option value="vane">Vane</option>
            <option value="billy">Billy</option>
        </o-select>
    </o-field>

    <o-field label="Disabled">
        <o-select placeholder="Select a character" disabled>
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
            <option value="vane">Vane</option>
            <option value="billy">Billy</option>
        </o-select>
    </o-field>

    <o-field label="Disabled options">
        <o-select placeholder="Select a character">
            <option value="flint" disabled>Flint</option>
            <option value="silver" disabled>Silver</option>
        </o-select>
    </o-field>

    <o-field label="Expanded">
        <o-select placeholder="Select a character" expanded>
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
            <option value="vane">Vane</option>
            <option value="billy" disabled>Billy</option>
        </o-select>
    </o-field>
</section>

Options

There are several ways to provide options for a select input:

• An array of primitives ['A', 'B', 'C']
• An object literal with key-value pairs { a: 'A', b: 'B', c: 'C' }
• An array of objects with label and value properties
• Using the native <option> tags directly inside the default slot.

Array of primitives

The simplest way to provide options is an array of primitives like strings or numbers, where the primitive will be used for both thestring casted label representation and the value of the option.

Show code

HTML

<section>
    <o-field label="Select a character">
        <o-select
            placeholder="Select a character"
            expanded
            icon="user"
            :options="[
                'Tyrion Lannister',
                'Jamie Lannister',
                'Daenerys Targaryen',
                'Jon Snow',
            ]" />
    </o-field>
</section>

Key-Value pair object

You may also provide the options prop where the keys are values and the values of each property are labels.

Show code

HTML

<section>
    <o-field label="Select a character">
        <o-select
            placeholder="Select a character"
            expanded
            icon="user"
            :options="{
                heisenberg: 'Heisenberg',
                jesse: 'Jesse',
                saul: 'Saul',
                mike: 'Mike',
                jack: 'Jack',
            }" />
    </o-field>
</section>

Array of objects

The most flexible way to define options is to provide an array of objects. The object is defined as:
{ value: any, label: string, attrs?: object }
The value attribute is the real value which will be used by the v-model property and other events. The label attribute is the visible representation of the option. The attrs attribute is an object for additional attributes, which will be applied to the option item tag.

Show code

HTML

<section>
    <o-field label="Select a character">
        <o-select
            placeholder="Select a character"
            expanded
            icon="user"
            :options="[
                { label: 'Flint', value: 'flint' },
                { label: 'Silver', value: 'silver' },
                { label: 'Vane', value: 'vane' },
                { label: 'Billy', value: 'billy' },
                {
                    label: 'Jack',
                    value: 'jack',
                    attrs: { disabled: true },
                },
            ]" />
    </o-field>
</section>

Option groups

Using the array of objects syntax you can also create grouped options (<optgroup> in HTML) by adding an options property to the object option.

Show code

HTML

<section>
    <o-field>
        <o-select
            v-model="selected"
            placeholder="Select a character"
            aria-label="Select a character"
            icon="user"
            expanded
            :options="[
                {
                    label: 'Names',
                    options: ['Flint', 'Silver', 'Vane', 'Jack'],
                },
                {
                    label: 'Numbers',
                    options: [1, 2, 3],
                },
            ]" />
    </o-field>

    <p><b>Selected:</b> {{ selected }}</p>
</section>

JS

import { ref } from "vue";

const selected = ref<string>("");

Default Slot

Sometimes it may be desirable to manually output the contents of a select list in order to create specialized structures. This can be done by using the default slot to explicitly output your options like the native HTML select element.

Show code

HTML

<section>
    <o-field label="Where would you prefer to live?">
        <o-select placeholder="Select a planet" expanded>
            <optgroup label="Inner Planets">
                <option value="mercury">Mercury</option>
                <option value="venus">Venus</option>
                <option value="earth">Earth</option>
                <option value="mars">Mars</option>
            </optgroup>
            <optgroup label="Outer planets">
                <option value="jupiter">Jupiter</option>
                <option value="saturn">Saturn</option>
                <option value="uranus">Uranus</option>
                <option value="neptune">Neptune</option>
            </optgroup>
        </o-select>
    </o-field>
</section>

Multiple

The input also supports a multiple attribute that allows multi-selection. When used the v-model attribute will be an array of values.

Accessibility Notes

Select inputs with the multiple attribute can be challenging for some users because they require holding-down the control or command keys to perform multiple selections. Depending on your audience, you may want to consider using a checkbox input instead.

Show code

HTML

<section>
    <o-field label="Multiple">
        <o-select v-model="selected" multiple native-size="8">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
            <option value="vane">Vane</option>
            <option value="billy">Billy</option>
            <option value="jack">Jack</option>
            <option value="heisenberg">Heisenberg</option>
            <option value="jesse">Jesse</option>
            <option value="saul">Saul</option>
            <option value="mike">Mike</option>
        </o-select>
    </o-field>

    <p><b>Selected:</b> {{ selected }}</p>
</section>

JS

import { ref } from "vue";

const selected = ref<string[]>([]);

Sizes

The component can be displayed in different sizes using the size prop.

Show code

HTML

<section>
    <o-field label="Small">
        <o-select placeholder="Select a character" size="small">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Default">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Medium">
        <o-select placeholder="Select a character" size="medium">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Large">
        <o-select placeholder="Select a character" size="large">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>
</section>

Variants

Different styles can be achieved with the variant prop.

Show code

HTML

<section>
    <o-field label="Primary" variant="primary">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Secondary" variant="secondary">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Success" variant="success">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Info" variant="info">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Warning" variant="warning">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field label="Danger" variant="danger">
        <o-select placeholder="Select a character">
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>
</section>

With Icons

Add an icon to the component to explain its function more visually.

Show code

HTML

<section>
    <o-field>
        <o-select
            placeholder="Select a name"
            aria-label="Select a name"
            icon="search"
            icon-clickable>
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>

    <o-field>
        <o-select
            placeholder="Select a name"
            aria-label="Select a name"
            icon="envelope"
            icon-right="times-circle"
            icon-right-clickable>
            <option value="flint">Flint</option>
            <option value="silver">Silver</option>
        </o-select>
    </o-field>
</section>

Select component

Select an item in a list. Use with Field to access all functionalities.

<o-select></o-select>

Props

Prop name	Description	Type	Values	Default
autocomplete	Same as native autocomplete options to use in HTML5 validation	string	-	From config: select: {   autocomplete: "off" }
customValidity	Custom HTML 5 validation error to set on the form control	string | ((currentValue: unknown, state: ValidityState) => string)	-
disabled	Disable the input - same as native disabled	boolean	-	false
expanded	Makes input full width when inside a grouped or addon field	boolean	-	false
icon	Icon to be shown	string	-	From config: select: {   icon: undefined }
iconClickable	Makes the icon clickable	boolean	-	false
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: select: {   iconPack: undefined }
iconRight	Icon to be added on the right side	string	-	From config: select: {   iconRight: undefined }
iconRightClickable	Make the icon right clickable	boolean	-	false
iconRightVariant	Variant of right icon	string	-
id	Same as native id. Also set the for label for o-field wrapper - default is an uuid.	string	-	useId()
v-model	The input value state	unknown	-
multiple	Allow multiple selection - converts the modelValue into an array	boolean	-
nativeSize	Same as native size	number | string	-
options	Select options, unnecessary when default slot is used	OptionsPropWithGroups<unknown>	-
override	Override existing theme classes completely	boolean	-
placeholder	Text when nothing is selected	string	-
required	Same as native required	boolean	-	false
rounded	Makes the element rounded	boolean	-	false
size	Vertical size of input	string	small, medium, large	From config: select: {   size: undefined }
statusIcon	Show status icon using field and variant prop	boolean	-	From config: {   statusIcon: true }
useHtml5Validation	Enable HTML 5 native validation	boolean	-	From config: {   useHtml5Validation: true }
variant	Color of the control	string	primary, info, success, warning, danger, and any other custom color	From config: select: {   variant: undefined }

Events

Event name	Properties	Description
update:model-value	value T | T[] - updated modelValue prop	modelValue prop two-way binding
focus	event Event - native event	on input focus event
blur	event Event - native event	on input blur event
invalid	event Event - native event	on input invalid event
icon-click	event Event - native event	on icon click event
icon-right-click	event Event - native event	on icon right click event

Slots

Name	Description	Bindings
placeholder	Override the placeholder
default	Override the options, default is options prop

Class Inspector

Classes applied to the element:

How does the Class props inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
sizeClass	Class of the root element with size.	size	small medium large
variantClass	Class of the root element with variant.	variant	primary info warning danger
expandedClass	Class of the root element when expanded.	expanded
disabledClass	Class of the root element when disabled.	disabled
roundedClass	Class of the root element when rounded.	rounded
hasIconRightClass	Class to the root element when a right icon is used.	iconRight
multipleClass	Class of the root element when multiple.	multiple
selectClass	Class of the native select element.
placeholderClass	Class of the native select element with a placeholder.
arrowedClass	Class of the native select element with an arrow. 👉 It applies the arrow icon using background-image and background-position on select element. An alternative to override this is the iconRight prop (globally or not).
iconLeftSpaceClass	Class of the native select element with left icon space.	icon
iconRightSpaceClass	Class of the native select element with right icon space.	iconRight
iconLeftClass	Class of the left icon element.	icon
iconRightClass	Class of the right icon element.	iconRight

Sass variables

Current theme ➜ Oruga

SASS Variable	Default
$select-background-color	#fff
$select-border-color	var(--#{$prefix}grey-lighter)
$select-border-style	solid
$select-border-width	1px
$select-border-radius	var(--#{$prefix}base-border-radius)
$select-rounded-border-radius	var( --#{$prefix}base-border-radius-rounded)
$select-box-shadow	$control-box-shadow
$select-color	#363636
$select-icon-zindex	4
$select-height	$control-height
$select-line-height	var(--#{$prefix}base-line-height)
$select-margin	0
$select-padding	$control-padding-vertical $control-padding-horizontal
$select-arrow-color	$select-color
$select-arrow-size	1rem
$select-placeholder-opacity	var(--#{$prefix}base-disabled-opacity)

See ➜ 📄 Full scss file

Current theme ➜ Bulma

The theme does not have any custom variables for this component.

Current theme ➜ Bootstrap

The theme does not have any custom variables for this component.