Vergil

Appearance

Select ​

Basic Usage ​

vue
<script setup>
import { Select } from '@8ctavio/vergil/components'
import { useModel } from '@8ctavio/vergil'

const difficulty = useModel('')
const difficultyOptions = {
    easy: 'Easy',
    normal: 'Normal',
    heroic: 'Heroic',
    legendary: 'Legendary'
}

const skulls = useModel([])
const skullOptions = {
    anger: 'Anger',
    blind: 'Blind',
    catch: 'Catch',
    ghost: 'Ghost',
}
</script>

<template>
    <!-- Single Selection -->
    <Select
        class="select-demo"
        v-model="difficulty"
        :options="difficultyOptions"
        label="Difficulty"
        placeholder="Choose difficulty"
    />
    <!-- Multiple Selection -->
    <Select
        class="select-demo"
        v-model="skulls"
        :options="skullOptions"
        label="Skulls"
        placeholder="Select skulls"
    />
</template>

<style scoped>
.select-demo {
    width: 200px;
}
</style>

<style>
#popover-portal > .popover-wrapper > .select-demo {
    width: 200px;
}   
</style>

Props ​

Options 
options: (string | [string, string])[] | Record<string, string | [string, string]> = []
 ​

The options prop is an array or (plain) object that provides the required data to define each option's value, label, and description, which correspond to the value, label, and description props of underlying Checkbox components.

Options' values, labels, and descriptions can be automatically inferred from the values of options — each denoted as option — if they're either a string or an array of strings.

The following table summarizes how option's label and description are inferred from an option.

Type of optionlabeldescription
stringoptionundefined
string[]option[0]option[1]

The following table summarizes how an option's value is inferred depending on the type of options.

Type of optionsvalue
ArraySame as label
objectThe option's key
Example. Options Array ​
vue
<script setup>
const options = [
    'Option 1',
    ['Option 2', 'Description 2']
]
</script>

<template>
    <Select v-model="selected" :options/>
</template>
selected.value === ''
Example. Options Object ​
vue
<script setup>
const options = {
    value1: 'Option 1',
    value2: ['Option 2', 'Description 2']
}
</script>

<template>
    <Select v-model="selected" :options/>
</template>
selected.value === ''

Option's attributes 
option-[value|label|description]: (string | Function)
 ​

The option-value, option-label, and option-description props allow to specify custom options' values, labels, and descriptions.

As strings, these props represent an object key. If an option is an object, the resulting value/label/description is obtained by accessing that object with the provided key.

vue
<script setup>
const options = [{
    id: '123',
    name: 'Abc Def',
    email: 'abc.def@vergil.com'
},{
    id: '456',
    name: 'Uvw Xyz',
    email: 'uvw.xyz@vergil.com'
}]
</script>

<template>
    <Select
        v-model="selected"
        :options
        option-value="id"    
        option-label="name"
        option-description="email"
    />
</template>
checked.value === ''

As functions, these props are called for each option, receive the option and its key (index for arrays) as arguments, and their return value becomes the resulting value/label/description.

vue
<script setup>
const options = [{
    id: '123',
    name: 'Abc Def',
    email: 'abc.def@vergil.com'
},{
    id: '456',
    name: 'Uvw Xyz',
    email: 'uvw.xyz@vergil.com'
}]
</script>

<template>
    <Select
        v-model="selected"
        :options
        :option-value="option => kebabCase(option.name)"    
        :option-label="option => option.name.split(' ')[0]"
        :option-description="option => `@@mail@@ ${option.email}`"
    />
</template>
checked.value === ''

The following functions are the default values for the option-value, option-label, and option-description props.

js
function defaultOptionValue(option, key) {
    return typeof key === 'number'
        ? Array.isArray(option) ? option[0] : option
        : key
}
function defaultOptionLabel(option) {
    return Array.isArray(option) ? option[0] : option
}
function defaultOptionDescription {
    return Array.isArray(option) ? option[1] : undefined
}

Placeholder 
placeholder: string
 ​

template
<Select placeholder="Select option"/>

Placeholder fallback 
placeholder-fallback: (n: number) => string
 ​

When selecting multiple options, the selected options are displayed in the select button as a comma-separated string of those options' labels. If that string overflows its container, a fallback placeholder is obtained from the placeholder-fallback function and displayed instead.

The placeholder-fallback function receives as its only argument the number of selected options.

vue
<script setup>
const options = ['The Fall of Reach', 'The Flood', 'First Strike']
</script>

<template>
    <Select :value="[]" :options
        :placeholder-fallback="n => {
            return `${n} Option${n > 1 ? 's':''} Selected`
        }"
        placeholder="Select option"
    />
</template>

The following function is used as the default placeholder-fallback value.

js
n => `${n} Selected`

TIP

The placeholder-fallback prop only takes effect in multiple selection mode.

Filter 
filter: boolean
 ​

vue
<script setup>
const options = ['abc','uvw','xyz']
</script>

<template>
    <Select :options filter placeholder="Select option"/>
</template>

Filter input 
filter-input: Record<string, unknown>
 ​

The filter-input prop is an object of props forwarded to the filter's InputText component.

vue
<script setup>
const options = ['Option']
</script>

<template>
    <Select :options filter placeholder="Select option"
        :filter-input="{
            placeholder: 'Filter users',
            icon: 'person_search',
            max: '10'
        }"
    />
</template>

TIP

The filter's default placeholder can be configured through the placeholderFilter configuration option.

Not-found placeholder 
placeholder-not-found: (query: string) => string
 
MiniMarkup
 ​

The placeholder-not-found prop is used to obtain a placeholder to display when the Select's filter input yields no results. The passed function receives as a single argument the filter input's query.

vue
<script setup>
const options = ['Option']
</script>

<template>
    <Select :options filter placeholder="Select option"
        :placeholder-not-found="query => {
            return `@@search_off@@\nCould not find [['${query}']]`
        }"
    />
</template>

The following function is used as the default placeholder-not-found value.

js
query => `No results for [["${query}"]]`

Chips 
chips: boolean
 Only for multiple selection ​

vue
<script setup>
const options = ['abc','uvw','xyz']
</script>

<template>
    <Select
        :value="[]"
        :options
        chips
        placeholder="Select option"
    />
</template>

Float label 
float-label: boolean
 ​

vue
<script setup>
const options = ['Option']
</script>

<template>
    <Select label="Select option" float-label :options/>
</template>

NOTE

float-label only works if the placeholder and description props are unset.

Underline 
underline: boolean
 ​

Fill 
fill: boolean
 ​

Theme 
theme: theme = 'brand'
 ​

Size 
size: ('xs' | 'sm' | 'md' | 'lg' | 'xl') = 'md'
 ​

Radius 
radius: ('none' | 'sm' | 'md' | 'lg' | 'full') = 'md'
 ​

Spacing 
spacing: ('compact' | 'expanded') = ''
 ​

Disabled 
disabled: boolean
 ​

Elements ​

elementtagdescription
options<div.toggle-group-wrapper>CheckboxGroup's wrapper of underlying Checkbox components.

Anatomy ​

<div.form-field.select/>

<div.form-field-label-wrapper/>

<label.form-field-label/>

<span.form-field-hint/>

<p.form-field-details.form-field-description/>

<Btn.btn.select-button/>

<p.select-placeholder/>

<span/>

<div.chips/>

<Badge.badge v-for="(label,value) in selected/>

<button/>

<Icon.icon/>

<template #aside/>

<label/>

<p.form-field-details.form-field-help/>

<Teleport#popover-portal/>

<div.popover-wrapper/>

<div.popover.select-popver/>

<Input.input-text/>

<p.select-not-found/>

<CheckboxGroup.checkbox-group/>

API Reference ​

Props ​

proptypedefault
valuestring | string[]''
options(string | [string, string])[] | Record<string, string | [string, string]>[]
optionValuestring | ((option: unknown, key: string | number) => string)
optionLabelstring | ((option: unknown, key: string | number) => string)
optionDescriptionstring | ((option: unknown, key: string | number) => string)
placeholderstring
placeholderFallback(n: number) => string
filterboolean
filterInputRecord<string, unknown>
placeholderNotFound(query: string) => string
chipsboolean
underlineboolean
disabledboolean
labelstring
hintstring
descriptionstring
helpstring
showErrrosboolean
float-labelboolean
descendantboolean
theme'brand' | 'user' | 'ok' | 'info' | 'warn' | 'danger' | 'neutral''brand'
size'xs' | 'sm' | 'md' | 'lg' | 'xl''md'
radius'none' | 'sm' | 'md' | 'lg' | 'full''md'
spacing'' | 'compact' | 'extended'''
validatorFunction
eagerValidationboolean
elementsobject

Configuration options ​

Select's configuration options allow to overwrite some Select props' default values and may be overwritten under the select root-level configuration option.

select.<option>typedefaultglobal
placeholderFallback(n: number) => stringn => `${n} Selected`
placeholderNotFound(query: string) => stringquery => `No results for [["${query}"]]`
placeholderFilterstring'Filter'
underlineboolean
fillboolean
themetheme✅
sizesize✅
radiusradius✅
spacingspacing✅