Vue Listbox Component

Usage

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

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  },
  {
    label: 'Netherlands',
    value: 'NL'
  },
  {
    label: 'Poland',
    value: 'PL'
  },
  {
    label: 'Belgium',
    value: 'BE'
  },
  {
    label: 'Portugal',
    value: 'PT'
  },
  {
    label: 'Austria',
    value: 'AT'
  }
])
const value = ref({
  label: 'France',
  value: 'FR'
})
</script>

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

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  },
  {
    label: 'Netherlands',
    value: 'NL'
  },
  {
    label: 'Poland',
    value: 'PL'
  },
  {
    label: 'Belgium',
    value: 'BE'
  },
  {
    label: 'Portugal',
    value: 'PT'
  },
  {
    label: 'Austria',
    value: 'AT'
  }
])
const value = ref({
  label: 'France',
  value: 'FR'
})
</script>

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

Items

Use the items prop as an array of objects with the following properties:

label?: string
description?: string
type?: "label" | "separator" | "item"
icon?: IconComponent
avatar?: AvatarProps
chip?: ChipProps
disabled?: boolean
onSelect?: (e: Event) => void
class?: any
b24ui?: { label?: ClassNameValue, separator?: ClassNameValue, item?: ClassNameValue, itemLeadingIcon?: ClassNameValue, ... }

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    description: 'The Hexagon',
    value: 'FR'
  },
  {
    label: 'Germany',
    description: 'The Federal Republic',
    value: 'DE'
  },
  {
    label: 'Italy',
    description: 'The Boot',
    value: 'IT'
  },
  {
    label: 'Spain',
    description: 'The Bull Skin',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    description: 'The Hexagon',
    value: 'FR'
  },
  {
    label: 'Germany',
    description: 'The Federal Republic',
    value: 'DE'
  },
  {
    label: 'Italy',
    description: 'The Boot',
    value: 'IT'
  },
  {
    label: 'Spain',
    description: 'The Bull Skin',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

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

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[][]>([
  [
    {
      label: 'France',
      value: 'FR'
    },
    {
      label: 'Germany',
      value: 'DE'
    },
    {
      label: 'Italy',
      value: 'IT'
    }
  ],
  [
    {
      label: 'Brazil',
      value: 'BR'
    },
    {
      label: 'Argentina',
      value: 'AR'
    }
  ]
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[][]>([
  [
    {
      label: 'France',
      value: 'FR'
    },
    {
      label: 'Germany',
      value: 'DE'
    },
    {
      label: 'Italy',
      value: 'IT'
    }
  ],
  [
    {
      label: 'Brazil',
      value: 'BR'
    },
    {
      label: 'Argentina',
      value: 'AR'
    }
  ]
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

Multiple

Use the multiple prop to allow selecting multiple items. When enabled, the v-model will be an array.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox multiple :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox multiple :items="items" />
</template>

Value Key

You can choose to bind a single property of the object rather than the whole object by using the value-key prop. Defaults to undefined.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
const value = ref('FR')
</script>

<template>
  <B24Listbox v-model="value" value-key="value" :items="items" class="w-full" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
const value = ref('FR')
</script>

<template>
  <B24Listbox v-model="value" value-key="value" :items="items" class="w-full" />
</template>

Filter

Use the filter prop to display a filter input or pass an object to customize the Input component. Defaults to false.

filter.placeholder

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  },
  {
    label: 'Netherlands',
    value: 'NL'
  },
  {
    label: 'Poland',
    value: 'PL'
  }
])
</script>

<template>
  <B24Listbox :filter="{
  placeholder: 'Filter...'
}" :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  },
  {
    label: 'Netherlands',
    value: 'NL'
  },
  {
    label: 'Poland',
    value: 'PL'
  }
])
</script>

<template>
  <B24Listbox :filter="{
  placeholder: 'Filter...'
}" :items="items" />
</template>

Selected Icon

Use the selected-icon prop to customize the icon when an item is selected.

<script setup lang="ts">
import RocketIcon from '@bitrix24/b24icons-vue/main/RocketIcon'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
const value = ref('FR')
</script>

<template>
  <B24Listbox v-model="value" :selected-icon="RocketIcon" value-key="value" :items="items" class="w-full" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import RocketIcon from '@bitrix24/b24icons-vue/main/RocketIcon'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
const value = ref('FR')
</script>

<template>
  <B24Listbox v-model="value" :selected-icon="RocketIcon" value-key="value" :items="items" class="w-full" />
</template>

Size

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

size

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox size="xl" :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox size="xl" :items="items" />
</template>

Loading

Use the loading prop to display a loading indicator. Use the loading-icon prop to customize the icon.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  }
])
</script>

<template>
  <B24Listbox loading :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  }
])
</script>

<template>
  <B24Listbox loading :items="items" />
</template>

Disabled

Use the disabled prop to prevent any user interaction with the Listbox.

disabled

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox disabled :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    value: 'FR'
  },
  {
    label: 'Germany',
    value: 'DE'
  },
  {
    label: 'Italy',
    value: 'IT'
  },
  {
    label: 'Spain',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox disabled :items="items" />
</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.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[][]>([
  [
    {
      type: 'label',
      label: 'Fruits'
    },
    {
      label: 'Apple'
    },
    {
      label: 'Banana'
    },
    {
      label: 'Blueberry'
    },
    {
      label: 'Grapes'
    },
    {
      label: 'Pineapple'
    }
  ],
  [
    {
      type: 'label',
      label: 'Vegetables'
    },
    {
      label: 'Aubergine'
    },
    {
      label: 'Broccoli'
    },
    {
      label: 'Carrot'
    },
    {
      label: 'Courgette'
    },
    {
      label: 'Leek'
    }
  ]
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[][]>([
  [
    {
      type: 'label',
      label: 'Fruits'
    },
    {
      label: 'Apple'
    },
    {
      label: 'Banana'
    },
    {
      label: 'Blueberry'
    },
    {
      label: 'Grapes'
    },
    {
      label: 'Pineapple'
    }
  ],
  [
    {
      type: 'label',
      label: 'Vegetables'
    },
    {
      label: 'Aubergine'
    },
    {
      label: 'Broccoli'
    },
    {
      label: 'Carrot'
    },
    {
      label: 'Courgette'
    },
    {
      label: 'Leek'
    }
  ]
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

When using label items as group headings, pass an array of arrays so a label gets filtered out together with its group when searching.

With icon in items

You can use the icon property to display an Icon inside the items.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import CircleCheckIcon from '@bitrix24/b24icons-vue/outline/CircleCheckIcon'
import CirclePlusIcon from '@bitrix24/b24icons-vue/outline/CirclePlusIcon'
import InfoCircleIcon from '@bitrix24/b24icons-vue/outline/InfoCircleIcon'
import SyncCircleIcon from '@bitrix24/b24icons-vue/main/SyncCircleIcon'

const items = ref<ListboxItem[]>([
  {
    label: 'Backlog',
    icon: InfoCircleIcon,
    value: 'backlog'
  },
  {
    label: 'Todo',
    icon: CirclePlusIcon,
    value: 'todo'
  },
  {
    label: 'In Progress',
    icon: SyncCircleIcon,
    value: 'in_progress'
  },
  {
    label: 'Done',
    icon: CircleCheckIcon,
    value: 'done'
  }
])
</script>

<template>
  <B24Listbox :items="items" class="w-full" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import CircleCheckIcon from '@bitrix24/b24icons-vue/outline/CircleCheckIcon'
import CirclePlusIcon from '@bitrix24/b24icons-vue/outline/CirclePlusIcon'
import InfoCircleIcon from '@bitrix24/b24icons-vue/outline/InfoCircleIcon'
import SyncCircleIcon from '@bitrix24/b24icons-vue/main/SyncCircleIcon'

const items = ref<ListboxItem[]>([
  {
    label: 'Backlog',
    icon: InfoCircleIcon,
    value: 'backlog'
  },
  {
    label: 'Todo',
    icon: CirclePlusIcon,
    value: 'todo'
  },
  {
    label: 'In Progress',
    icon: SyncCircleIcon,
    value: 'in_progress'
  },
  {
    label: 'Done',
    icon: CircleCheckIcon,
    value: 'done'
  }
])
</script>

<template>
  <B24Listbox :items="items" class="w-full" />
</template>

With avatar in items

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

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'Assistant',
    avatar: {
      src: '/b24ui/avatar/assistant.png'
    }
  },
  {
    label: 'Employee',
    avatar: {
      src: '/b24ui/avatar/employee.png'
    }
  },
  {
    label: 'Bitrix24',
    avatar: {
      src: 'https://github.com/bitrix24.png'
    }
  }
])
</script>

<template>
  <B24Listbox :items="items" class="w-full" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'Assistant',
    avatar: {
      src: '/b24ui/avatar/assistant.png'
    }
  },
  {
    label: 'Employee',
    avatar: {
      src: '/b24ui/avatar/employee.png'
    }
  },
  {
    label: 'Bitrix24',
    avatar: {
      src: 'https://github.com/bitrix24.png'
    }
  }
])
</script>

<template>
  <B24Listbox :items="items" class="w-full" />
</template>

With chip in items

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

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'bug',
    chip: {
      color: 'air-primary-alert'
    }
  },
  {
    label: 'feature',
    chip: {
      color: 'air-primary-success'
    }
  },
  {
    label: 'enhancement',
    chip: {
      color: 'air-primary'
    }
  }
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'bug',
    chip: {
      color: 'air-primary-alert'
    }
  },
  {
    label: 'feature',
    chip: {
      color: 'air-primary-success'
    }
  },
  {
    label: 'enhancement',
    chip: {
      color: 'air-primary'
    }
  }
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

With description in items

You can use the description property to display additional text below the label.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    description: 'The Hexagon',
    value: 'FR'
  },
  {
    label: 'Germany',
    description: 'The Federal Republic',
    value: 'DE'
  },
  {
    label: 'Italy',
    description: 'The Boot',
    value: 'IT'
  },
  {
    label: 'Spain',
    description: 'The Bull Skin',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'

const items = ref<ListboxItem[]>([
  {
    label: 'France',
    description: 'The Hexagon',
    value: 'FR'
  },
  {
    label: 'Germany',
    description: 'The Federal Republic',
    value: 'DE'
  },
  {
    label: 'Italy',
    description: 'The Boot',
    value: 'IT'
  },
  {
    label: 'Spain',
    description: 'The Bull Skin',
    value: 'ES'
  }
])
</script>

<template>
  <B24Listbox :items="items" />
</template>

Control selected items

You can control the selected item by using the default-value prop or the v-model directive.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import Location1Icon from '@bitrix24/b24icons-vue/main/Location1Icon'

const items: ListboxItem[] = [
  { label: 'France', icon: Location1Icon, value: 'FR' },
  { label: 'Germany', icon: Location1Icon, value: 'DE' },
  { label: 'Italy', icon: Location1Icon, value: 'IT' },
  { label: 'Spain', icon: Location1Icon, value: 'ES' },
  { label: 'Netherlands', icon: Location1Icon, value: 'NL' },
  { label: 'Poland', icon: Location1Icon, value: 'PL' }
]

const value = ref<ListboxItem>(items[2]!)
</script>

<template>
  <B24Listbox
    v-model="value"
    :items="items"
    class="w-full"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import Location1Icon from '@bitrix24/b24icons-vue/main/Location1Icon'

const items: ListboxItem[] = [
  { label: 'France', icon: Location1Icon, value: 'FR' },
  { label: 'Germany', icon: Location1Icon, value: 'DE' },
  { label: 'Italy', icon: Location1Icon, value: 'IT' },
  { label: 'Spain', icon: Location1Icon, value: 'ES' },
  { label: 'Netherlands', icon: Location1Icon, value: 'NL' },
  { label: 'Poland', icon: Location1Icon, value: 'PL' }
]

const value = ref<ListboxItem>(items[2]!)
</script>

<template>
  <B24Listbox
    v-model="value"
    :items="items"
    class="w-full"
  />
</template>

Control search term

Use the v-model:search-term directive to control the search term.

<script setup lang="ts">
import Location1Icon from '@bitrix24/b24icons-vue/main/Location1Icon'

const searchTerm = ref('F')
const items = ref([
  { label: 'France', icon: Location1Icon, value: 'FR' },
  { label: 'Germany', icon: Location1Icon, value: 'DE' },
  { label: 'Italy', icon: Location1Icon, value: 'IT' },
  { label: 'Spain', icon: Location1Icon, value: 'ES' },
  { label: 'Netherlands', icon: Location1Icon, value: 'NL' },
  { label: 'Poland', icon: Location1Icon, value: 'PL' }
])
const value = ref()
</script>

<template>
  <B24Listbox v-model="value" v-model:search-term="searchTerm" filter :items="items" class="w-full" />
</template>

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

const searchTerm = ref('F')
const items = ref([
  { label: 'France', icon: Location1Icon, value: 'FR' },
  { label: 'Germany', icon: Location1Icon, value: 'DE' },
  { label: 'Italy', icon: Location1Icon, value: 'IT' },
  { label: 'Spain', icon: Location1Icon, value: 'ES' },
  { label: 'Netherlands', icon: Location1Icon, value: 'NL' },
  { label: 'Poland', icon: Location1Icon, value: 'PL' }
])
const value = ref()
</script>

<template>
  <B24Listbox v-model="value" v-model:search-term="searchTerm" filter :items="items" class="w-full" />
</template>

With ignore filter

Set the ignore-filter prop to true to disable the internal search and use your own search logic.

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

const searchTerm = ref('')
const searchTermDebounced = refDebounced(searchTerm, 200)

const { data: users, status, execute } = await useLazyFetch('https://jsonplaceholder.typicode.com/users', {
  key: 'listbox-users-search',
  params: { q: searchTermDebounced },
  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}`, loading: 'lazy' as const }
    }))
  },
  immediate: false
})

onMounted(() => {
  execute()
})
</script>

<template>
  <B24Listbox
    v-model:search-term="searchTerm"
    :items="users || []"
    :filter="{
      icon: CrmSearchIcon,
      loading: status === 'pending'
    }"
    ignore-filter
    class="w-full"
  />
</template>

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

const searchTerm = ref('')
const searchTermDebounced = refDebounced(searchTerm, 200)

const { data: users, status, execute } = await useLazyFetch('https://jsonplaceholder.typicode.com/users', {
  key: 'listbox-users-search',
  params: { q: searchTermDebounced },
  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}`, loading: 'lazy' as const }
    }))
  },
  immediate: false
})

onMounted(() => {
  execute()
})
</script>

<template>
  <B24Listbox
    v-model:search-term="searchTerm"
    :items="users || []"
    :filter="{
      icon: CrmSearchIcon,
      loading: status === 'pending'
    }"
    ignore-filter
    class="w-full"
  />
</template>

This example uses refDebounced to debounce the API calls.

With filter fields

Use the filter-fields prop with an array of fields to filter on. Defaults to [labelKey].

<script setup lang="ts">
const { data: users, status, execute } = await useLazyFetch('https://jsonplaceholder.typicode.com/users', {
  key: 'typicode-users-email',
  transform: (data: { id: number, name: string, email: string }[]) => {
    return data?.map(user => ({
      label: user.name,
      email: user.email,
      value: String(user.id),
      avatar: { src: `https://i.pravatar.cc/120?img=${user.id}`, loading: 'lazy' as const }
    }))
  },
  immediate: false
})

onMounted(() => {
  execute()
})
</script>

<template>
  <B24Listbox
    :items="users || []"
    :loading="status === 'pending'"
    :filter-fields="['label', 'email']"
    filter
    class="w-full"
  >
    <template #item-label="{ item }">
      {{ item.label }}

      <span class="text-muted">
        {{ item.email }}
      </span>
    </template>
  </B24Listbox>
</template>

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

const { data: users, status, execute } = await useLazyFetch('https://jsonplaceholder.typicode.com/users', {
  key: 'typicode-users-email',
  transform: (data: { id: number, name: string, email: string }[]) => {
    return data?.map(user => ({
      label: user.name,
      email: user.email,
      value: String(user.id),
      avatar: { src: `https://i.pravatar.cc/120?img=${user.id}`, loading: 'lazy' as const }
    }))
  },
  immediate: false
})

onMounted(() => {
  execute()
})
</script>

<template>
  <B24Listbox
    :items="users || []"
    :loading="status === 'pending'"
    :filter-fields="['label', 'email']"
    filter
    class="w-full"
  >
    <template #item-label="{ item }">
      {{ item.label }}

      <span class="text-muted">
        {{ item.email }}
      </span>
    </template>
  </B24Listbox>
</template>

With virtualization

Use the virtualize prop to enable virtualization for large lists as a boolean or an object with options like { estimateSize: 32, overscan: 12 }.

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import FileIcon from '@bitrix24/b24icons-vue/outline/FileIcon'

const items: ListboxItem[] = Array.from({ length: 1000 }, (_, i) => ({
  label: `Item ${i + 1}`,
  icon: FileIcon,
  value: i + 1
}))

const value = ref<ListboxItem[]>([])
</script>

<template>
  <B24Listbox
    v-model="value"
    :items="items"
    multiple
    virtualize
    class="w-full"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import FileIcon from '@bitrix24/b24icons-vue/outline/FileIcon'

const items: ListboxItem[] = Array.from({ length: 1000 }, (_, i) => ({
  label: `Item ${i + 1}`,
  icon: FileIcon,
  value: i + 1
}))

const value = ref<ListboxItem[]>([])
</script>

<template>
  <B24Listbox
    v-model="value"
    :items="items"
    multiple
    virtualize
    class="w-full"
  />
</template>

As a transfer list

You can compose two Listbox components with Button controls to build a transfer list pattern.

Available

Selected

<script setup lang="ts">
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import Location1Icon from '@bitrix24/b24icons-vue/main/Location1Icon'
import ChevronLeftLIcon from '@bitrix24/b24icons-vue/outline/ChevronLeftLIcon'
import ChevronRightLIcon from '@bitrix24/b24icons-vue/outline/ChevronRightLIcon'

const items: ListboxItem[] = [
  { label: 'France', icon: Location1Icon, value: 'FR' },
  { label: 'Germany', icon: Location1Icon, value: 'DE' },
  { label: 'Italy', icon: Location1Icon, value: 'IT' },
  { label: 'Spain', icon: Location1Icon, value: 'ES' },
  { label: 'Netherlands', icon: Location1Icon, value: 'NL' },
  { label: 'Poland', icon: Location1Icon, value: 'PL' },
  { label: 'Belgium', icon: Location1Icon, value: 'BE' },
  { label: 'Portugal', icon: Location1Icon, value: 'PT' }
]

const targetItems = ref<ListboxItem[]>([])
const sourceSelection = ref<ListboxItem[]>([])
const targetSelection = ref<ListboxItem[]>([])

const sourceItems = computed(() => items.filter(item => !targetItems.value.some(t => t.value === item.value)))

function transferSelected() {
  targetItems.value = [...targetItems.value, ...sourceSelection.value]
  sourceSelection.value = []
}

function removeSelected() {
  targetItems.value = targetItems.value.filter(item => !targetSelection.value.some(t => t.value === item.value))
  targetSelection.value = []
}
</script>

<template>
  <div class="flex items-stretch gap-4 w-full">
    <div class="flex flex-col flex-1 gap-1">
      <span class="text-sm font-medium text-highlighted">Available</span>

      <B24Listbox
        v-model="sourceSelection"
        :items="sourceItems"
        multiple
        filter
        class="size-full"
      />
    </div>

    <div class="flex flex-col items-center justify-center gap-1">
      <B24Button
        :icon="ChevronRightLIcon"
        :disabled="!sourceSelection.length"
        @click="transferSelected"
      />
      <B24Button
        :icon="ChevronLeftLIcon"
        :disabled="!targetSelection.length"
        @click="removeSelected"
      />
    </div>

    <div class="flex flex-col flex-1 gap-1">
      <span class="text-sm font-medium text-legend">Selected</span>

      <B24Listbox
        v-model="targetSelection"
        :items="targetItems"
        multiple
        filter
        class="size-full"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'
import type { ListboxItem } from '@bitrix24/b24ui-nuxt'
import Location1Icon from '@bitrix24/b24icons-vue/main/Location1Icon'
import ChevronLeftLIcon from '@bitrix24/b24icons-vue/outline/ChevronLeftLIcon'
import ChevronRightLIcon from '@bitrix24/b24icons-vue/outline/ChevronRightLIcon'

const items: ListboxItem[] = [
  { label: 'France', icon: Location1Icon, value: 'FR' },
  { label: 'Germany', icon: Location1Icon, value: 'DE' },
  { label: 'Italy', icon: Location1Icon, value: 'IT' },
  { label: 'Spain', icon: Location1Icon, value: 'ES' },
  { label: 'Netherlands', icon: Location1Icon, value: 'NL' },
  { label: 'Poland', icon: Location1Icon, value: 'PL' },
  { label: 'Belgium', icon: Location1Icon, value: 'BE' },
  { label: 'Portugal', icon: Location1Icon, value: 'PT' }
]

const targetItems = ref<ListboxItem[]>([])
const sourceSelection = ref<ListboxItem[]>([])
const targetSelection = ref<ListboxItem[]>([])

const sourceItems = computed(() => items.filter(item => !targetItems.value.some(t => t.value === item.value)))

function transferSelected() {
  targetItems.value = [...targetItems.value, ...sourceSelection.value]
  sourceSelection.value = []
}

function removeSelected() {
  targetItems.value = targetItems.value.filter(item => !targetSelection.value.some(t => t.value === item.value))
  targetSelection.value = []
}
</script>

<template>
  <div class="flex items-stretch gap-4 w-full">
    <div class="flex flex-col flex-1 gap-1">
      <span class="text-sm font-medium text-highlighted">Available</span>

      <B24Listbox
        v-model="sourceSelection"
        :items="sourceItems"
        multiple
        filter
        class="size-full"
      />
    </div>

    <div class="flex flex-col items-center justify-center gap-1">
      <B24Button
        :icon="ChevronRightLIcon"
        :disabled="!sourceSelection.length"
        @click="transferSelected"
      />
      <B24Button
        :icon="ChevronLeftLIcon"
        :disabled="!targetSelection.length"
        @click="removeSelected"
      />
    </div>

    <div class="flex flex-col flex-1 gap-1">
      <span class="text-sm font-medium text-legend">Selected</span>

      <B24Listbox
        v-model="targetSelection"
        :items="targetItems"
        multiple
        filter
        class="size-full"
      />
    </div>
  </div>
</template>

API

Props

Prop	Default	Type
`as`	`'div'`	`any` The element or component this component should render as.
`id`		`string`
`color`	`'air-primary'`	`"air-primary" \| "air-primary-success" \| "air-primary-alert" \| "air-primary-warning" \| "air-primary-copilot"`
`size`	`'md'`	`"sm" \| "md" \| "xs" \| "lg" \| "xss" \| "xl"`
`items`		`T` The items to display in the list.
`modelValue`		`_Number<_Optional<_Nullable<GetModelValue<T, VK, M, undefined>, Mod>, Mod>, Mod>` The controlled value of the Listbox. Can be bound with `v-model`.
`modelModifiers`		`Mod`
`defaultValue`		`_Number<_Optional<_Nullable<GetModelValue<T, VK, M, undefined>, Mod>, Mod>, Mod>` The default value when not controlled.
`multiple`	`false`	`M` Whether multiple items can be selected.
`valueKey`	`undefined`	`VK` When `items` is an array of objects, select the field to use as the value instead of the object itself.
`labelKey`	`'label'`	`keyof Extract<NestedItem<T>, object> & string \| DotPathKeys<Extract<NestedItem<T>, object>>` The key used to get the label from the item.
`descriptionKey`	`'description'`	`keyof Extract<NestedItem<T>, object> & string \| DotPathKeys<Extract<NestedItem<T>, object>>` The key used to get the description from the item.
`loading`		`boolean` Whether the list is in a loading state.
`loadingIcon`	`icons.loading`	`IconComponent` The icon displayed when loading.
`filter`	`false`	`boolean \| Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" \| "defaultValue">` Whether to display a filter input or not. Can be an object to pass additional props to the input. `{ placeholder: 'Search...', variant: 'none' }`
`filterFields`	`[labelKey]`	`string[]` The fields to filter by.
`ignoreFilter`	`false`	`boolean` When `true`, disable the default filters, useful for custom filtering (useAsyncData, useFetch, etc.).
`selectedIcon`	`icons.check`	`IconComponent` The icon displayed when an item is selected.
`virtualize`	`false`	`boolean \| { overscan?: number ; estimateSize?: number \| ((index: number) => number) \| undefined; } \| undefined` Enable virtualization for large lists.
`highlight`		`boolean` Highlight the ring color like a focus state.
`autofocus`		`boolean`
`autofocusDelay`	`0`	`number`
`by`		`string \| (a: AcceptableValue, b: AcceptableValue): boolean` Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
`disabled`		`boolean` When `true`, prevents the user from interacting with listbox
`highlightOnHover`	`true`	`boolean` When `true`, hover over item will trigger highlight
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`orientation`		`"vertical" \| "horizontal"` The orientation of the listbox. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`selectionBehavior`	`'toggle'`	`"replace" \| "toggle"` How multiple selection should behave in the collection.
`searchTerm`	`''`	`string`
`b24ui`		`{ root?: SlotClass; input?: SlotClass; content?: SlotClass; group?: SlotClass; label?: SlotClass; separator?: SlotClass; empty?: SlotClass; loading?: SlotClass; loadingIcon?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; }`

Slots

Slot	Type
`loading`	`{}`
`empty`	`{ searchTerm: string; }`
`item`	`{ item: NestedItem<T>; index: number; b24ui: object; }`
`item-leading`	`{ item: NestedItem<T>; index: number; b24ui: object; }`
`item-label`	`{ item: NestedItem<T>; index: number; }`
`item-description`	`{ item: NestedItem<T>; index: number; }`
`item-trailing`	`{ item: NestedItem<T>; index: number; b24ui: object; }`

Emits

Event	Type
`entryFocus`	`[event: CustomEvent<any>]`
`highlight`	`[payload: { ref: HTMLElement; value: AcceptableValue; } \| undefined]`
`leave`	`[event: Event]`
`change`	`[event: Event]`
`update:modelValue`	`[value: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, undefined>, Mod>, Mod>, Mod>]`
`update:searchTerm`	`[value: string]`

Theme

https://github.com/bitrix24/b24ui/tree/main/src/theme/listbox.ts

export default {
  slots: {
    root: 'flex flex-col min-h-0 min-w-0 ring ring-inset ring-(--ui-color-design-outline-stroke) rounded-lg overflow-hidden outline-(--b24ui-border-color) has-focus-visible:outline-3 has-focus-visible:ring-(--b24ui-border-color)',
    input: 'border-b border-(--ui-color-design-outline-stroke) has-focus-visible:border-(--b24ui-border-color)',
    content: 'relative overflow-y-auto flex-1 max-h-60 scroll-py-1 focus:outline-none',
    group: 'isolate',
    label: 'w-full min-w-[195px] h-(--popup-window-delimiter-section-height) px-4.5 mt-(--menu-item-block-stack-space) flex flex-row rtl:flex-row-reverse items-center select-none outline-none whitespace-nowrap text-start text-(length:--ui-size-sm) text-legend font-(--ui-font-weight-normal) after:ms-[10px] after:block after:flex-1 after:min-w-[15px] after:h-px after:bg-(--ui-color-divider-vibrant-default)',
    separator: 'my-2 mx-4.5 h-[1px] bg-(--ui-color-divider-vibrant-default)',
    empty: 'py-2 select-none outline-none whitespace-nowrap text-center text-(length:--popup-window-delimiter-font-size)/(--ui-font-line-height-lg) text-legend font-(--ui-font-weight-normal)',
    loading: 'flex items-center justify-center text-muted',
    loadingIcon: 'shrink-0',
    item: 'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-0 data-disabled:cursor-not-allowed data-disabled:opacity-75 text-default data-highlighted:not-data-disabled:text-label data-[state=checked]:text-label data-highlighted:not-data-disabled:before:bg-(--ui-color-base-black-fixed)/3 dark:data-highlighted:not-data-disabled:before:bg-(--ui-color-base-black-fixed) transition-colors before:transition-colors',
    itemLeadingIcon: 'size-[25px] shrink-0 text-(--ui-color-base-5)',
    itemLeadingAvatar: 'shrink-0',
    itemLeadingAvatarSize: '',
    itemLeadingChip: 'shrink-0',
    itemLeadingChipSize: '',
    itemWrapper: 'flex-1 flex flex-col min-w-0',
    itemLabel: 'truncate',
    itemDescription: 'truncate -mt-[6px] text-description text-(length:--ui-font-size-sm)',
    itemTrailing: 'ml-auto rtl:ml-0 rtl:mr-auto inline-flex gap-1.5 items-center',
    itemTrailingIcon: 'shrink-0 text-(--ui-color-accent-main-primary)'
  },
  variants: {
    size: {
      xss: {
        label: 'p-1 text-[10px]/3 gap-1',
        empty: 'py-3 text-[10px]',
        loading: 'py-3',
        loadingIcon: 'size-2',
        item: 'p-1 text-[10px] gap-1',
        itemLeadingIcon: 'size-3 mt-0.5',
        itemLeadingAvatar: 'size-3 mt-0.5',
        itemLeadingAvatarSize: '3xs',
        itemLeadingChip: 'size-3 mt-0.5',
        itemLeadingChipSize: '2xs',
        itemTrailingIcon: 'size-3 mt-0.5'
      },
      xs: {
        label: 'p-1 text-[10px]/3 gap-1',
        empty: 'py-3 text-[12px]',
        loading: 'py-3',
        loadingIcon: 'size-[12px]',
        item: 'p-1 text-[12px] gap-1',
        itemLeadingIcon: 'size-4 mt-0.5',
        itemLeadingAvatar: 'size-4 mt-0.5',
        itemLeadingAvatarSize: '3xs',
        itemLeadingChip: 'size-3 mt-0.5',
        itemLeadingChipSize: 'sm',
        itemTrailingIcon: 'size-4 mt-0.5'
      },
      sm: {
        label: 'p-1.5 text-[10px]/3 gap-1.5',
        empty: 'py-4 text-[14px]',
        loading: 'py-4',
        loadingIcon: 'size-4',
        item: 'p-1.5 text-[14px] gap-1.5',
        itemLeadingIcon: 'size-5',
        itemLeadingAvatar: 'size-5',
        itemLeadingAvatarSize: '3xs',
        itemLeadingChip: 'size-4 mt-1',
        itemLeadingChipSize: 'sm',
        itemTrailingIcon: 'size-5'
      },
      md: {
        label: 'px-4.5 py-1.5 text-xs gap-1.5',
        empty: 'py-6 text-4',
        loading: 'py-6',
        loadingIcon: 'size-6',
        item: 'px-4.5 py-1.5 text-4 gap-1.5',
        itemLeadingIcon: 'size-6',
        itemLeadingAvatar: 'size-6',
        itemLeadingAvatarSize: '2xs',
        itemLeadingChip: 'size-5 mt-1',
        itemLeadingChipSize: 'md',
        itemTrailingIcon: 'size-6'
      },
      lg: {
        label: 'p-2 text-xs gap-2',
        empty: 'py-7 text-4',
        loading: 'py-7',
        loadingIcon: 'size-8',
        item: 'p-2 text-4 gap-2',
        itemLeadingIcon: 'size-7',
        itemLeadingAvatar: 'size-7',
        itemLeadingAvatarSize: '2xs',
        itemLeadingChip: 'size-5 mt-1',
        itemLeadingChipSize: 'md',
        itemTrailingIcon: 'size-6'
      },
      xl: {
        label: 'p-2 text-4 gap-2',
        empty: 'py-8 text-6',
        loading: 'py-8',
        loadingIcon: 'size-10',
        item: 'p-2 text-6 gap-2',
        itemLeadingIcon: 'size-7',
        itemLeadingAvatar: 'size-7',
        itemLeadingAvatarSize: 'xs',
        itemLeadingChip: 'size-6',
        itemLeadingChipSize: 'lg',
        itemTrailingIcon: 'size-6',
        itemDescription: 'text-4'
      }
    },
    color: {
      'air-primary': {
        root: 'style-filled'
      },
      'air-primary-success': {
        root: 'style-filled-success'
      },
      'air-primary-alert': {
        root: 'style-filled-alert'
      },
      'air-primary-copilot': {
        root: 'style-filled-copilot'
      },
      'air-primary-warning': {
        root: 'style-filled-warning'
      }
    },
    virtualize: {
      true: {
        content: 'p-1 isolate'
      },
      false: {
        content: 'divide-y divide-(--ui-color-divider-default)'
      }
    },
    disabled: {
      true: {
        root: 'cursor-not-allowed opacity-30'
      }
    },
    highlight: {
      true: 'ring ring-inset ring-(--b24ui-border-color)'
    }
  },
  compoundVariants: [],
  defaultVariants: {
    color: 'air-primary',
    size: 'md'
  }
}

InputTime

A time selection input field.

PinInput

A PIN code input component.