Select

A selection field to pick from various options.

Usage

Use the v-model directive to control the value of the Select or the default-value prop to set the initial value when you do not need to control its state.

Items

Use the items prop as an array of strings, numbers or booleans:

INFO

If you need to limit the height of a dropdown list, you can use custom style parameters.

For example, to set the maximum height of the list to 60 units, add the parameter :b24ui="{ content: 'max-h-60' }".

This will help control the content display and improve the user experience.

vue

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['CRM settings', 'My company details', 'Access permissions', 'CRM Payment', 'CRM.Delivery', 'Scripts', 'Create script', 'Install from Bitrix24.Market'])
const value = ref('CRM Payment')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    class="w-3/4"
  />
  <B24Separator class="my-3 w-3/4" label="fix height" type="dotted" />
  <B24Select
    :items="items"
    default-value="My company details"
    class="w-3/4"
    :b24ui="{ content: 'max-h-60' }"
  />
</template>

You can also pass an array of objects with the following properties:

label?: string
value?: string
type?: "label" | "separator" | "item"
icon?: FunctionalComponent<HTMLAttributes & VNodeProps>
avatar?: AvatarProps
chip?: ChipProps
disabled?: boolean

DANGER

When using objects, you need to reference the value property of the object in the v-model directive or the default-value prop.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const items = ref([
  {
    label: 'CRM settings',
    value: 'settings'
  },
  {
    label: 'My company details',
    value: 'my_company_details'
  },
  {
    label: 'Access permissions',
    value: 'access_permissions'
  }
])
const value = ref('my_company_details')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
  />
</template>

You can also pass an array of arrays to the items prop to display separated groups of items.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const items = ref([
  ['CRM settings', 'My company details', 'Access permissions', 'CRM Payment', 'CRM.Delivery'],
  ['Scripts', 'Create script', 'Install from Bitrix24.Market']
])
const value = ref('CRM Payment')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
  />
</template>

Value Key

You can change the property that is used to set the value by using the value-key prop. Defaults to value.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const items = ref([
  {
    label: 'CRM settings',
    id: 'settings'
  },
  {
    label: 'My company details',
    id: 'my_company_details'
  },
  {
    label: 'Access permissions',
    id: 'access_permissions'
  }
])
const value = ref('my_company_details')
</script>

<template>
  <B24Select
    v-model="value"
    value-key="id"
    :items="items"
  />
</template>

Multiple

Use the multiple prop to allow multiple selections, the selected items will be separated by a comma in the trigger.

DANGER

Ensure to pass an array to the default-value prop or the v-model directive.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['CRM settings', 'My company details', 'Access permissions', 'CRM Payment', 'CRM.Delivery', 'Scripts', 'Create script', 'Install from Bitrix24.Market'])
const value = ref(['CRM Payment', 'My company details'])
</script>

<template>
  <B24Select
    v-model="value"
    multiple
    :items="items"
  />
</template>

Placeholder

Use the placeholder prop to set a placeholder text.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

export interface ExampleProps {
  placeholder?: string
}

withDefaults(defineProps<ExampleProps>(), {
  placeholder: 'You need to choose'
})

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :placeholder="placeholder"
  />
</template>

Content

Use the content prop to control how the Select content is rendered, like its align or side for example.

Details

vue

<script setup lang="ts">
import { ref, computed } from 'vue'

export interface ExampleProps {
  contentAlign?: 'start' | 'center' | 'end'
  contentSide?: 'top' | 'right' | 'bottom' | 'left'
  contentSideOffset?: number
}

const props = withDefaults(defineProps<ExampleProps>(), {
  contentAlign: 'start',
  contentSide: 'left',
  contentSideOffset: 8
})

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')

const content = computed(() => {
  return {
    align: props.contentAlign,
    side: props.contentSide,
    sideOffset: props.contentSideOffset
  }
})
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :content="content"
  />
</template>

Arrow

Use the arrow prop to display an arrow on the Select.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('Access permissions')
</script>

<template>
  <B24Select
    v-model="value"
    arrow
    :items="items"
  />
</template>

Color

Use the color prop to change the ring color when the Select is focused.

INFO

The highlight prop is used here to show the focus state. It's used internally when a validation error occurs.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

export interface ExampleProps {
  color: any
  isHighlight?: boolean
}

withDefaults(defineProps<ExampleProps>(), {
  color: 'default',
  isHighlight: true
})

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('Access permissions')
</script>

<template>
  <B24Select
    v-model="value"
    :color="color"
    :highlight="isHighlight"
    :items="items"
  />
</template>

Tag

Use the tag property to display a small legend on top of the Select.

Use the tagColor property to set the color for tag.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

export interface ExampleProps {
  tagColor: any
  tag?: string
}

withDefaults(defineProps<ExampleProps>(), {
  tagColor: 'default',
  tag: 'info'
})

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('Access permissions')
</script>

<template>
  <B24Select
    v-model="value"
    :tag-color="tagColor"
    :tag="tag"
    :items="items"
  />
</template>

Size

Use the size prop to change the size of the Select.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

export interface ExampleProps {
  size?: any
}

withDefaults(defineProps<ExampleProps>(), {
  size: 'md'
})

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('Access permissions')
</script>

<template>
  <B24Select
    v-model="value"
    :size="size"
    :items="items"
  />
</template>

Icon

Use the icon prop to show an @bitrix24/b24icons inside the Select.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'
import CrmSearchIcon from '@bitrix24/b24icons-vue/crm/CrmSearchIcon'

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :icon="CrmSearchIcon"
  />
</template>

Trailing Icon

Use the trailing-icon prop to customize the trailing @bitrix24/b24icons. Defaults to Actions::ChevronDownIcon.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'
import Expand1Icon from '@bitrix24/b24icons-vue/actions/Expand1Icon'

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :trailing-icon="Expand1Icon"
  />
</template>

Selected Icon

Use the selected-icon prop to customize the icon when an item is selected. Defaults to Main::CheckIcon.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'
import CheckInBoxIcon from '@bitrix24/b24icons-vue/crm/CheckInBoxIcon'

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :selected-icon="CheckInBoxIcon"
  />
</template>

Avatar

Use the avatar prop to show an Avatar inside the Select.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'
import Bitrix24Icon from '@bitrix24/b24icons-vue/common-service/Bitrix24Icon'

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :avatar="{ src: '/b24ui/avatar/employee.png' }"
  />
  <B24Select
    v-model="value"
    :items="items"
    :avatar="{ icon: Bitrix24Icon }"
  />
</template>

Loading

Use the loading prop to show a loading icon on the Select.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

export interface ExampleProps {
  isLoading?: boolean
}

withDefaults(defineProps<ExampleProps>(), {
  isLoading: true
})

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :loading="isLoading"
  />
</template>

Disabled

Use the disabled prop to disable the Select.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

export interface ExampleProps {
  isDisabled?: boolean
}

withDefaults(defineProps<ExampleProps>(), {
  isDisabled: true
})

const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :disabled="isDisabled"
  />
</template>

Examples

With items type

You can use the type property with separator to display a separator between items or label to display a label.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const items = ref([
  {
    type: 'label',
    label: 'CRM'
  },
  'CRM settings',
  'My company details',
  'Access permissions',
  {
    type: 'separator'
  },
  {
    type: 'label',
    label: 'Smart scripts'
  },
  'Scripts',
  'Create script',
  'Install from Bitrix24.Market'
])
const value = ref('Access permissions')
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
  />
</template>

With icons in items

You can use the icon property to display an @bitrix24/b24icons inside the items.

INFO

In this example, the icon is computed from the value property of the selected item.

TIP

You can also use the #leading slot to display the selected icon.

Details

vue

<script setup lang="ts">
import { ref, computed } from 'vue'
import SettingsIcon from '@bitrix24/b24icons-vue/main/SettingsIcon'
import MyPlanIcon from '@bitrix24/b24icons-vue/main/MyPlanIcon'
import Shield2DefendedIcon from '@bitrix24/b24icons-vue/main/Shield2DefendedIcon'

const items = ref([
  {
    label: 'CRM settings',
    value: 'settings',
    icon: SettingsIcon
  },
  {
    label: 'My company details',
    value: 'my_company_details',
    icon: MyPlanIcon
  },
  {
    label: 'Access permissions',
    value: 'access_permissions',
    icon: Shield2DefendedIcon
  }
])
const value = ref('my_company_details')

const icon = computed(() => items.value.find(item => item.value === value.value)?.icon)
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :icon="icon"
  />
</template>

With avatar in items

You can use the avatar property to display an Avatar inside the items.

INFO

In this example, the avatar is computed from the value property of the selected item.

TIP

You can also use the #leading slot to display the selected avatar.

Details

vue

<script setup lang="ts">
import { ref, computed } from 'vue'

const items = ref([
  {
    label: 'Assistant',
    value: 'assistant',
    avatar: {
      src: '/b24ui/avatar/assistant.png',
      alt: 'assistant'
    }
  },
  {
    label: 'Employee',
    value: 'employee',
    avatar: {
      src: '/b24ui/avatar/employee.png',
      alt: 'employee'
    }
  }
])
const value = ref('employee')

const avatar = computed(() => items.value.find(item => item.value === value.value)?.avatar)
</script>

<template>
  <B24Select
    v-model="value"
    :items="items"
    :avatar="avatar"
  />
</template>

With chip in items

You can use the chip property to display a Chip inside the items.

INFO

In this example, the #leading slot is used to display the selected chip.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const chipItems = ref([
  {
    label: 'default',
    value: 'default',
    chip: {
      color: 'default' as const
    }
  },
  {
    label: 'danger',
    value: 'danger',
    chip: {
      color: 'danger' as const
    }
  }
])
const chipValue = ref((chipItems.value[0]?.value))

function getChip(value: string) {
  return chipItems.value.find(item => item.value === value)?.chip
}
</script>

<template>
  <B24Select
    v-model="chipValue"
    :items="chipItems"
    name="color"
    class="w-full"
  >
    <template #leading="{ modelValue, b24ui }">
      <B24Chip
        v-if="modelValue"
        v-bind="getChip(modelValue as string)"
        inset
        standalone
        :size="b24ui.itemLeadingChipSize()"
        :class="b24ui.itemLeadingChip()"
      />
    </template>
  </B24Select>
</template>

Control open state

You can control the open state by using the default-open prop or the v-model:open directive.

INFO

In this example, leveraging defineShortcuts, you can toggle the Select by pressing O.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')

defineShortcuts({
  o: () => open.value = !open.value
})
</script>

<template>
  <B24Tooltip text="You can toggle the Select by pressing" :kbds="['O']" :content="{ side: 'top' }">
    <B24Select
      v-model="value"
      v-model:open="open"
      :items="items"
    />
  </B24Tooltip>
</template>

With rotating icon

Here is an example with a rotating icon that indicates the open state of the Select.

Details

vue

<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const items = ref(['CRM settings', 'My company details', 'Access permissions'])
const value = ref('My company details')
</script>

<template>
  <B24Select
    v-model="value"
    v-model:open="open"
    :items="items"
    :b24ui="{
      trailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200'
    }"
  />
</template>

With fetched items

You can fetch items from an API and use them in the Select.

Details

vue

<script setup lang="ts">
import UserIcon from '@bitrix24/b24icons-vue/common-b24/UserIcon'
import Expand1Icon from '@bitrix24/b24icons-vue/actions/Expand1Icon'

const { data: users, status: status } = await globalThis.useFetch('https://jsonplaceholder.typicode.com/users', {
  transform: (data: { id: number, name: string }[]) => {
    return data?.map(user => ({
      label: user.name,
      value: String(user.id),
      avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` }
    })) || []
  },
  lazy: true
})

function getUserAvatar(value: string) {
  return users.value?.find(user => user.value === value)?.avatar || {}
}
</script>

<template>
  <B24Select
    :items="users"
    :loading="status === 'pending'"
    :icon="UserIcon"
    :trailing-icon="Expand1Icon"
    placeholder="Search users&hellip;"
  >
    <template #leading="{ modelValue, b24ui }">
      <B24Avatar
        v-if="modelValue"
        v-bind="getUserAvatar(modelValue as string)"
        :size="b24ui.leadingAvatarSize()"
        :class="b24ui.leadingAvatar()"
      />
    </template>
  </B24Select>
</template>

API

Props

Prop	Default	Type
`id`		`string`
`placeholder`		`string` The placeholder text when the select is empty.
`color`		`"default" \| "danger" \| "success" \| "warning" \| "primary" \| "secondary" \| "collab" \| "ai"`
`size`		`"lg" \| "md" \| "xs" \| "sm"`
`noPadding`		`boolean` Removes padding from input.
`noBorder`		`boolean` removes all borders (rings).
`underline`		`boolean` removes all borders (rings) except the bottom one.
`rounded`		`boolean` Rounds the corners of the button.
`tag`		`string`
`tagColor`		`"default" \| "danger" \| "success" \| "warning" \| "primary" \| "secondary" \| "collab" \| "ai"`
`trailingIcon`	icons.chevronDown = `ChevronDownIcon`	`(props: HTMLAttributes & VNodeProps & {}, ctx: Omit<{ attrs: Data; slots: Readonly<InternalSlots>; emit: (event: string, ...args: any[]) => void; expose: <Exposed extends Record<string, any> = Record<...>>(exposed?: Exposed) => void; }, "expose">): any` The icon displayed to open the menu.
`selectedIcon`	icons.check = `CheckIcon`	`(props: HTMLAttributes & VNodeProps & {}, ctx: Omit<{ attrs: Data; slots: Readonly<InternalSlots>; emit: (event: string, ...args: any[]) => void; expose: <Exposed extends Record<string, any> = Record<...>>(exposed?: Exposed) => void; }, "expose">): any` The icon displayed when an item is selected.
`content`	`{ side: 'bottom', sideOffset: 8, collisionPadding: 8, position: 'popper' }`	`Omit<SelectContentProps, "as" \| "asChild" \| "forceMount">` The content of the menu.
`arrow`	`false`	`boolean \| Omit<SelectArrowProps, "as" \| "asChild">` Display an arrow alongside the menu.
`portal`	`true`	`boolean` Render the menu in a portal.
`valueKey`	`"value" as never`	`string` When `items` is an array of objects, select the field to use as the value.
`labelKey`	`"label" as never`	`string` When `items` is an array of objects, select the field to use as the label.
`items`		`(boolean \| AcceptableValue \| SelectItem)[] \| (boolean \| AcceptableValue \| SelectItem)[][]`
`defaultValue`		`any` The value of the Select when initially rendered. Use when you do not need to control the state of the Select.
`modelValue`		`any` The controlled value of the Select. Can be bind as `v-model`.
`multiple`		`boolean` Whether multiple options can be selected or not.
`highlight`		`boolean` Highlight the ring color like a focus state.
`b24ui`		`PartialString<{ root: string; base: string; leading: string; leadingIcon: string; leadingAvatar: string; leadingAvatarSize: string; trailing: string; trailingIcon: string; tag: string; value: string; placeholder: string; ... 17 more ...; itemLabel: string; }>`
`disabled`		`boolean` When `true`, prevents the user from interacting with Select
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`defaultOpen`		`boolean` The open state of the select when it is initially rendered. Use when you do not need to control its open state.
`open`		`boolean` The controlled open state of the Select. Can be bind as `v-model:open`.
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`autocomplete`		`string` Native html input `autocomplete` attribute.
`icon`		`(props: HTMLAttributes & VNodeProps & {}, ctx: Omit<{ attrs: Data; slots: Readonly<InternalSlots>; emit: (event: string, ...args: any[]) => void; expose: <Exposed extends Record<string, any> = Record<...>>(exposed?: Exposed) => void; }, "expose">): any` Display an icon on the left side.
`avatar`		`AvatarProps` Display an avatar on the left side.
`loading`		`boolean` When `true`, the loading icon will be displayed.
`trailing`		`boolean` When `true`, the icon will be displayed on the right side.

Slots

Slot	Type
`leading`	`{ modelValue?: AcceptableValue \| AcceptableValue[]; open: boolean; b24ui: any; }`
`default`	`{ modelValue?: AcceptableValue \| AcceptableValue[]; open: boolean; }`
`trailing`	`{ modelValue?: AcceptableValue \| AcceptableValue[]; open: boolean; b24ui: any; }`
`item`	`{ item: boolean \| AcceptableValue \| SelectItem; index: number; }`
`item-leading`	`{ item: boolean \| AcceptableValue \| SelectItem; index: number; }`
`item-label`	`{ item: boolean \| AcceptableValue \| SelectItem; index: number; }`
`item-trailing`	`{ item: boolean \| AcceptableValue \| SelectItem; index: number; }`

Emits

Event	Type

Select ​

Usage ​

Items ​

Value Key ​

Multiple ​

Placeholder ​

Content ​

Arrow ​

Color ​

Tag ​

Size ​

Icon ​

Trailing Icon ​

Selected Icon ​

Avatar ​

Loading ​

Disabled ​

Examples ​

With items type ​

With icons in items ​

With avatar in items ​

With chip in items ​

Control open state ​

With rotating icon ​

With fetched items ​

API ​

Props ​

Slots ​

Emits ​

Select

Usage

Items

Value Key

Multiple

Placeholder

Content

Arrow

Color

Tag

Size

Icon

Trailing Icon

Selected Icon

Avatar

Loading

Disabled

Examples

With items type

With icons in items

With avatar in items

With chip in items

Control open state

With rotating icon

With fetched items

API

Props

Slots

Emits