QSelect 🔽

Select component is a component that allows users pick a single value or a several values from predefined options. Ideally, it should be used if you have more than 5 options, otherwise you might consider using a radio group instead. Try storyopen in new window

Examples

A few scenarios:

Props

modelValue

Type: String | Number | Array | Object,
Default: null

The binding value. As you can see there are a lot of types supported, Array is being used for a multiple mode - to choose several values. Let's check the types:

// TS type
type QSelectPropModelValue = Nullable<
  string | number | QOptionPropValue | (string | number | QOptionPropValue)[]
>;

type QOptionPropValue = string | number | Record<string, unknown>;

1
2
3
4
5
6

modelValue as String:

Template:

<template>
  <q-select v-model="value">
    <q-option
      v-for="item in options"
      :key="item"
      :label="item"
      :value="item"
    />
  </q-select>
</template>

1
2
3
4
5
6
7
8
9
10

Component instance:

export default {
  setup() {
    const options = ['value', 'value2'];
    const value = ref('value');
    return { value };
  }
};

1
2
3
4
5
6
7

modelValue as Object:

NOTE

The modelValue as Object MUST be used with one of requirements:

the modelValue MUST contain the value field.
set your custom value-key to <q-select value-key="..."> to bind you value with options.

Template:

<template>
  <q-select v-model="modelValue">
    <q-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item"
    />
  </q-select>
</template>

1
2
3
4
5
6
7
8
9
10

Component instance:

export default {
  setup() {
    // ...
    const modelValue = Vue.ref({
      value: 'value1',
      label: 'Option 1'
    });

    const options = [
      {
        value: 'value1',
        label: 'Option 1'
      },
      {
        value: 'value2',
        label: 'Option 2'
      }
    ];

    return { modelValue, options };
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

OPTIONS

The modelValue syncs with options by the value prop. So don't forget to pass a value in <q-option>
Learn more about <q-option>

valueKey

Type: String
Default: 'value'

Custom key name for value when the modelValue is object.

Template:

<template>
  <q-select
    v-model="modelValue"
    value-key="id"
  >
    <q-option
      v-for="item in options"
      :key="item.id"
      :label="item.label"
      :value="item.id"
    />
  </q-select>
</template>

1
2
3
4
5
6
7
8
9
10
11
12
13

Component instance:

export default {
  setup() {
    // ...
    const modelValue = Vue.ref({
      id: 'value1',
      label: 'Option 1'
    });

    const options = [
      {
        id: 'value1',
        label: 'Option 1'
      },
      {
        id: 'value2',
        label: 'Option 2'
      }
    ];

    return { modelValue, ... }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

multiple

Type: Boolean
Default: false

You can think multiple is a mode allows you to select several values. There are several additional props to customize the mode.

multiple additional props

Prop	Type	Default	Description
`multipleLimit`	`Number`	`0`	Maximum number of options user can select when `multiple` is true. No limit when set to `0` number.
`selectAllShown`	`Boolean`	`false`	Whether `Select all` button is shown
`selectAllText`	`String`	`null`	Custom `Select all` button text
`collapseTags`	`Boolean`	`false`	Only `1` choosen option is shown inside input, the rest is hidden by counter

multiple mode examples:

Template:

<template>
  <q-select
    multiple
    collapse-tags
    :multiple-limit="2"
    select-all-text="Select all cities"
    ...
  >
</template>

1
2
3
4
5
6
7
8
9

disabled

Type: Boolean
Default: false

Whether QSelect is disabled.

<q-select
  disabled
  ...
>

1
2
3
4

filterable

Type: Boolean
Default: false

Allows typing and filtering options.

<template>
  <q-select
    filterable
    ...
  >
</template>

1
2
3
4
5
6

clearable

Type: Boolean
Default: false

Adds the clear button to remove selected on hover.

<q-select
  clearable
  ...
>

1
2
3
4

remote

Type: Boolean
Default: false

Whether options loads from server.

You can think remote is a mode, so there are a few additional props to customize the mode:

remote additional props

Prop	Type	Default	Description
`loading`	`Boolean`	`false`	Whether `QSelect` is loading.
`loadingText`	`String`	`null`	Text that is shown when `loading` is true.
`loadMoreText`	`String`	`null`	Additional text in the end of options list is being shown when `canLoadMore` is `true`. Inform users you have more options on server and ask specify the query string. Use with `canLoadMore`:
`canLoadMore`	`Boolean`	`false`	Whether `loadMoreText` is shown.
`noMatchText`	`String`	`null`	When no matching happend
`noDataText`	`String`	`null`	When no options got

remote mode example:

Template:

<template>
  <q-select
    v-model="valueSearch"
    :loading="isLoading"
    :can-load-more="canLoadMore"
    @search="handleSearch"
    placeholder="Search by label"
    loading-text="Searching options..."
    filterable
    remote
  >
    <q-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </q-select>
</template>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Component instance:

export default {
  setup() {
    const valueSearch = Vue.ref(null);
    const isLoading = Vue.ref(false);
    const options = Vue.ref([]);

    const optionsServer = [
      {
        value: 'value0',
        label: 'Option Zero'
      },
      {
        value: 'value1',
        label: 'Option 1'
      },
      {
        value: 'value3',
        label:
          'Lorem Ipsum is simply dummy text of the printing and typesetting industry.'
      }
    ];

    const canLoadMore = Vue.ref(false);

    const handleSearch = query => {
      options.value = [];
      isLoading.value = true;

      // request imitation
      setTimeout(() => {
        options.value = optionsServer.filter(
          option =>
            option.label.toLowerCase().search(query.toLowerCase()) !== -1
        );
        isLoading.value = false;
        canLoadMore.value = optionsServer.length === options.value.length;
      }, 1000);
    };

    return {
      options,
      valueSearch,
      handleSearch,
      isLoading,
      canLoadMore
    };
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

allowCreate

Type Boolean
Default: false

Whether creating new items is allowed.

WARNING

To use allowCreate, filterable must be true.

placeholder

Type: String
Default: null

As native placeholderopen in new window.

<q-select
  placeholder="Select the city"
  ...
>

1
2
3
4

autocomplete

Type: String
Default: 'off'

As native autocompleteopen in new window input's attribute.

<q-select
  autocomplete="on"
  ...
>

1
2
3
4

teleportTo

Type String, HTMLElement
Default: null

Specifies a target element where QSelect will be moved from original layout place. (has to be a valid query selector, or an HTMLElement).

<template>
  <q-select
    ...
    teleport-to="body"
  />
</template>

1
2
3
4
5
6

Events

update:modelValue

Triggers when the model is being updated.

<template>
  <q-select
    ...
    @update:modelValue="handleModelValueUpdate"
  />
</template>

1
2
3
4
5
6

change

Alias for update:modelValue

<template>
  <q-select
    ...
    @change="handleModelValueUpdate"
  />
</template>

1
2
3
4
5
6

input

Triggers when native input event fires.

<template>
  <q-select
    ...
    @input="handleModelValueInput"
  />
</template>

1
2
3
4
5
6

focus

Triggers when select gets focus.

<template>
  <q-select
    ...
    @focus="handleSelectFocus"
  />
</template>

1
2
3
4
5
6

blur

Triggers when select gets blur.

<template>
  <q-select
    ...
    @blur="handleSelectBlur"
  />
</template>

1
2
3
4
5
6

clear

Triggers when clear button clicks.

<template>
  <q-select
    ...
    @clear="handleSelectClear"
  />
</template>

1
2
3
4
5
6

remove-tag

Triggers when tag removes in multiple mode.

<template>
  <q-select
    ...
    @remove-tag="handleTagRemove"
    multiple
  />
</template>

1
2
3
4
5
6
7

search

Triggers when search query changes in remote mode.

<template>
  <q-select
    ...
    @search="handleSelectSearch"
    remote
  />
</template>

1
2
3
4
5
6
7

visible-change

Triggers when dropdown state changes.

<template>
  <q-select
    ...
    @visible-change="handleDropdownToggle"
  />
</template>

1
2
3
4
5
6

Slots

default

Default slot is being used to keep <q-options> list only.

WARNING

Do not set any another content into default slot.

empty

Used to put your custom content istead of <q-options>

<template>
  <q-select
    v-model="value"
    placeholder="Open to see the magic"
  >
    <template #empty>
      <div class="block">Magic! Your custom content</div>
    </template>
  </q-select>
</template>

1
2
3
4
5
6
7
8
9
10

QOption

QOption is an additional component to control options. Use with v-for directive to render options list.

<template>
  <q-select v-model="value">
    <q-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </q-select>
</template>

1
2
3
4
5
6
7
8
9
10

export default {
  setup() {
    const options = [
      { value: 'one', label: 'One' }
      { value: 'two', label: 'Two' }
    ];

    const value = ref('value');
    return { value, options }
  }
}

1
2
3
4
5
6
7
8
9
10
11

An Option's list MUST be an Array of Strings, Numbers or on Objects:

type Options = (string | number | Option)[];

interface Option {
  value: Nullable<QOptionPropValue>;
  label?: Nullable<string | number>;
  disabled?: Nullable<boolean>;
}

type QOptionPropValue = string | number | Record<string, unknown>;

1
2
3
4
5
6
7
8
9

QOption props

value

Type: String | Number | Object
Required: true

An option's value that QSelect is trying to mach with the modelValue.

export type QOptionPropValue = string | number | Record<string, unknown>;

label

Type: String | Number
Default: null

The label is being shown as an Option title.

disabled

Type: Boolean
Default: false

Whether option is disabled.

<template>
  <q-select
    v-model="value"
    placeholder="Pick an option"
  >
    <q-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
      :disabled="item.disabled"
    />
  </q-select>
</template>

1
2
3
4
5
6
7
8
9
10
11
12
13
14

export default {
  setup() {
    const options = [
      {
        value: 0,
        label: 'Option Zero',
        disabled: true,
      },
      {
        value: 'value1',
        label: 'Option 1',
        disabled: true,
      },
    ];

    ...

    return { options, ... }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# QSelect 🔽

# Examples

# Props

# modelValue

# valueKey

# multiple

# multiple additional props

# multiple mode examples:

# disabled

# filterable

# clearable

# remote

# remote additional props

# remote mode example:

# allowCreate

# placeholder

# autocomplete

# teleportTo

# Events

# update:modelValue

# change

# input

# focus

# blur

# clear

# remove-tag

# search

# visible-change

# Slots

# default

# empty

# QOption

# QOption props

# value

# label

# disabled

QSelect 🔽

Examples

Props

modelValue

valueKey

multiple

multiple additional props

multiple mode examples:

disabled

filterable

clearable

remote

remote additional props

remote mode example:

allowCreate

placeholder

autocomplete

teleportTo

Events

update:modelValue

change

input

focus

blur

clear

remove-tag

search

visible-change

Slots

default

empty

QOption

QOption props

value

label

disabled