ListBox

A listbox displays a list of options and allows a user to select one or more of them.

Import

import { ListBox, ListBoxItem, ListBoxItemIndicator, ListBoxSection } from '@heroui-vue/vue'

Usage

<template>
  <ListBox aria-label="Users" class="demo-list-box" selection-mode="single">
    <ListBoxItem id="1" text-value="Bob">
      <Avatar size="sm">
        <AvatarImage alt="Bob" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
        <AvatarFallback>B</AvatarFallback>
      </Avatar>
      <div class="demo-list-box-user">
        <Label>Bob</Label>
        <Description>bob@heroui.com</Description>
      </div>
      <ListBoxItemIndicator />
    </ListBoxItem>
    <ListBoxItem id="2" text-value="Fred">
      <Avatar size="sm">
        <AvatarImage alt="Fred" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
        <AvatarFallback>F</AvatarFallback>
      </Avatar>
      <div class="demo-list-box-user">
        <Label>Fred</Label>
        <Description>fred@heroui.com</Description>
      </div>
      <ListBoxItemIndicator />
    </ListBoxItem>
    <ListBoxItem id="3" text-value="Martha">
      <Avatar size="sm">
        <AvatarImage alt="Martha" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
        <AvatarFallback>M</AvatarFallback>
      </Avatar>
      <div class="demo-list-box-user">
        <Label>Martha</Label>
        <Description>martha@heroui.com</Description>
      </div>
      <ListBoxItemIndicator />
    </ListBoxItem>
  </ListBox>
</template>

<script setup lang="ts">
import { Avatar, AvatarFallback, AvatarImage, Description, Label, ListBox, ListBoxItem, ListBoxItemIndicator } from '@heroui-vue/vue'
</script>

<style lang="less">
.demo-list-box {
  width: 13.75rem;
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}
</style>

Anatomy

vue

<ListBox>
  <ListBoxItem>
    <Label />
    <Description />
    <ListBoxItemIndicator />
  </ListBoxItem>
  <ListBoxSection>
    <Header />
    <ListBoxItem>
      <Label />
    </ListBoxItem>
  </ListBoxSection>
</ListBox>

With Sections

<template>
  <Surface class="demo-list-box-surface">
    <ListBox aria-label="File actions" class="demo-list-box-actions" selection-mode="none" @action="handleAction">
      <ListBoxSection>
        <Header>Actions</Header>
        <ListBoxItem id="new-file" text-value="New file">
          <div class="demo-list-box-action-icon">
            <svg aria-hidden="true" fill="none" viewBox="0 0 16 16">
              <path d="M8 3v10M3 8h10" stroke="currentColor" stroke-linecap="round" stroke-width="1.8" />
            </svg>
          </div>
          <div class="demo-list-box-user">
            <Label>New file</Label>
            <Description>Create a new file</Description>
          </div>
          <Kbd class="demo-list-box-kbd" :keys="['⌘']" variant="light">N</Kbd>
        </ListBoxItem>
        <ListBoxItem id="edit-file" text-value="Edit file">
          <div class="demo-list-box-action-icon">
            <svg aria-hidden="true" fill="none" viewBox="0 0 16 16">
              <path d="M10.9 2.6 13.4 5.1 6.2 12.3 3 13l.7-3.2 7.2-7.2Z" stroke="currentColor" stroke-linejoin="round" stroke-width="1.5" />
            </svg>
          </div>
          <div class="demo-list-box-user">
            <Label>Edit file</Label>
            <Description>Make changes</Description>
          </div>
          <Kbd class="demo-list-box-kbd" :keys="['⌘']" variant="light">E</Kbd>
        </ListBoxItem>
      </ListBoxSection>
      <Separator />
      <ListBoxSection>
        <Header>Danger zone</Header>
        <ListBoxItem id="delete-file" text-value="Delete file" variant="danger">
          <div class="demo-list-box-action-icon demo-list-box-action-icon--danger">
            <svg aria-hidden="true" fill="none" viewBox="0 0 16 16">
              <path d="M3.5 4.5h9M6.5 2.5h3M5 4.5l.5 9h5l.5-9" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" />
            </svg>
          </div>
          <div class="demo-list-box-user">
            <Label>Delete file</Label>
            <Description>Move to trash</Description>
          </div>
          <Kbd class="demo-list-box-kbd" :keys="['⌘', '⇧']" variant="light">D</Kbd>
        </ListBoxItem>
      </ListBoxSection>
    </ListBox>
  </Surface>
</template>

<script setup lang="ts">
import { Description, Header, Kbd, Label, ListBox, ListBoxItem, ListBoxSection, Separator, Surface } from '@heroui-vue/vue'

const handleAction = (key: string | number) => {
  window.alert(`Selected item: ${key}`)
}
</script>

<style lang="less">
.demo-list-box-surface {
  width: 16rem;
  border-radius: 1.5rem;
  box-shadow: var(--shadow-surface);
}

.demo-list-box-actions {
  width: 100%;
  padding: 0.5rem;
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}

.demo-list-box-action-icon {
  display: flex;
  height: 2rem;
  align-items: flex-start;
  justify-content: center;
  padding-top: 0.0625rem;
  color: var(--color-muted);

  svg {
    width: 1rem;
    height: 1rem;
    flex-shrink: 0;
  }
}

.demo-list-box-action-icon--danger {
  color: var(--color-danger);
}

.demo-list-box-kbd {
  margin-inline-start: auto;
}
</style>

Multi Select

<template>
  <Surface class="demo-list-box-surface">
    <ListBox aria-label="Users" selection-mode="multiple">
      <ListBoxItem v-for="user in users" :id="user.id" :key="user.id" :text-value="user.name">
        <Avatar size="sm">
          <AvatarImage :alt="user.name" :src="user.avatar" />
          <AvatarFallback>{{ user.fallback }}</AvatarFallback>
        </Avatar>
        <div class="demo-list-box-user">
          <Label>{{ user.name }}</Label>
          <Description>{{ user.email }}</Description>
        </div>
        <ListBoxItemIndicator />
      </ListBoxItem>
    </ListBox>
  </Surface>
</template>

<script setup lang="ts">
import { Avatar, AvatarFallback, AvatarImage, Description, Label, ListBox, ListBoxItem, ListBoxItemIndicator, Surface } from '@heroui-vue/vue'

const users = [
  { id: '1', name: 'Bob', email: 'bob@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg', fallback: 'B' },
  { id: '2', name: 'Fred', email: 'fred@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg', fallback: 'F' },
  { id: '3', name: 'Martha', email: 'martha@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg', fallback: 'M' },
]
</script>

<style lang="less">
.demo-list-box-surface {
  width: 16rem;
  border-radius: 1.5rem;
  box-shadow: var(--shadow-surface);
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}
</style>

With Disabled Items

<template>
  <Surface class="demo-list-box-surface">
    <ListBox
      aria-label="File actions"
      class="demo-list-box-actions"
      :disabled-keys="['delete-file']"
      selection-mode="none"
      @action="handleAction"
    >
      <ListBoxSection>
        <Header>Actions</Header>
        <ListBoxItem id="new-file" text-value="New file">
          <div class="demo-list-box-action-icon">
            <svg aria-hidden="true" fill="none" viewBox="0 0 16 16">
              <path d="M8 3v10M3 8h10" stroke="currentColor" stroke-linecap="round" stroke-width="1.8" />
            </svg>
          </div>
          <div class="demo-list-box-user">
            <Label>New file</Label>
            <Description>Create a new file</Description>
          </div>
          <Kbd class="demo-list-box-kbd" :keys="['⌘']" variant="light">N</Kbd>
        </ListBoxItem>
        <ListBoxItem id="edit-file" text-value="Edit file">
          <div class="demo-list-box-action-icon">
            <svg aria-hidden="true" fill="none" viewBox="0 0 16 16">
              <path d="M10.9 2.6 13.4 5.1 6.2 12.3 3 13l.7-3.2 7.2-7.2Z" stroke="currentColor" stroke-linejoin="round" stroke-width="1.5" />
            </svg>
          </div>
          <div class="demo-list-box-user">
            <Label>Edit file</Label>
            <Description>Make changes</Description>
          </div>
          <Kbd class="demo-list-box-kbd" :keys="['⌘']" variant="light">E</Kbd>
        </ListBoxItem>
      </ListBoxSection>
      <Separator />
      <ListBoxSection>
        <Header>Danger zone</Header>
        <ListBoxItem id="delete-file" text-value="Delete file" variant="danger">
          <div class="demo-list-box-action-icon demo-list-box-action-icon--danger">
            <svg aria-hidden="true" fill="none" viewBox="0 0 16 16">
              <path d="M3.5 4.5h9M6.5 2.5h3M5 4.5l.5 9h5l.5-9" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" />
            </svg>
          </div>
          <div class="demo-list-box-user">
            <Label>Delete file</Label>
            <Description>Move to trash</Description>
          </div>
          <Kbd class="demo-list-box-kbd" :keys="['⌘', '⇧']" variant="light">D</Kbd>
        </ListBoxItem>
      </ListBoxSection>
    </ListBox>
  </Surface>
</template>

<script setup lang="ts">
import { Description, Header, Kbd, Label, ListBox, ListBoxItem, ListBoxSection, Separator, Surface } from '@heroui-vue/vue'

const handleAction = (key: string | number) => {
  window.alert(`Selected item: ${key}`)
}
</script>

<style lang="less">
.demo-list-box-surface {
  width: 16rem;
  border-radius: 1.5rem;
  box-shadow: var(--shadow-surface);
}

.demo-list-box-actions {
  width: 100%;
  padding: 0.5rem;
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}

.demo-list-box-action-icon {
  display: flex;
  height: 2rem;
  align-items: flex-start;
  justify-content: center;
  padding-top: 0.0625rem;
  color: var(--color-muted);

  svg {
    width: 1rem;
    height: 1rem;
    flex-shrink: 0;
  }
}

.demo-list-box-action-icon--danger {
  color: var(--color-danger);
}

.demo-list-box-kbd {
  margin-inline-start: auto;
}
</style>

Custom Check Icon

<template>
  <Surface class="demo-list-box-surface">
    <ListBox aria-label="Users" selection-mode="multiple">
      <ListBoxItem v-for="user in users" :id="user.id" :key="user.id" :text-value="user.name">
        <Avatar size="sm">
          <AvatarImage :alt="user.name" :src="user.avatar" />
          <AvatarFallback>{{ user.fallback }}</AvatarFallback>
        </Avatar>
        <div class="demo-list-box-user">
          <Label>{{ user.name }}</Label>
          <Description>{{ user.email }}</Description>
        </div>
        <ListBoxItemIndicator>
          <template #default="{ isSelected }">
            <svg v-if="isSelected" aria-hidden="true" class="demo-list-box-check" fill="none" viewBox="0 0 16 16">
              <path d="M3.5 8.5 6.5 11.5 12.5 4.5" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" />
            </svg>
          </template>
        </ListBoxItemIndicator>
      </ListBoxItem>
    </ListBox>
  </Surface>
</template>

<script setup lang="ts">
import { Avatar, AvatarFallback, AvatarImage, Description, Label, ListBox, ListBoxItem, ListBoxItemIndicator, Surface } from '@heroui-vue/vue'

const users = [
  { id: '1', name: 'Bob', email: 'bob@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg', fallback: 'B' },
  { id: '2', name: 'Fred', email: 'fred@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg', fallback: 'F' },
  { id: '3', name: 'Martha', email: 'martha@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg', fallback: 'M' },
]
</script>

<style lang="less">
.demo-list-box-surface {
  width: 16rem;
  border-radius: 1.5rem;
  box-shadow: var(--shadow-surface);
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}

.demo-list-box-check {
  width: 1rem;
  height: 1rem;
  color: var(--color-accent);
}
</style>

Controlled

Selected: 1

<template>
  <div class="demo-list-box-controlled">
    <Surface class="demo-list-box-surface">
      <ListBox v-model:selected-keys="selected" aria-label="Users" selection-mode="multiple">
        <ListBoxItem v-for="user in users" :id="user.id" :key="user.id" :text-value="user.name">
          <Avatar size="sm">
            <AvatarImage :alt="user.name" :src="user.avatar" />
            <AvatarFallback>{{ user.fallback }}</AvatarFallback>
          </Avatar>
          <div class="demo-list-box-user">
            <Label>{{ user.name }}</Label>
            <Description>{{ user.email }}</Description>
          </div>
          <ListBoxItemIndicator>
            <template #default="{ isSelected }">
              <svg v-if="isSelected" aria-hidden="true" class="demo-list-box-check" fill="none" viewBox="0 0 16 16">
                <path d="M3.5 8.5 6.5 11.5 12.5 4.5" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" />
              </svg>
            </template>
          </ListBoxItemIndicator>
        </ListBoxItem>
      </ListBox>
    </Surface>
    <p>Selected: {{ selected.length > 0 ? selected.join(', ') : 'None' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Avatar, AvatarFallback, AvatarImage, Description, Label, ListBox, ListBoxItem, ListBoxItemIndicator, Surface } from '@heroui-vue/vue'

const selected = ref<Array<string | number>>(['1'])
const users = [
  { id: '1', name: 'Bob', email: 'bob@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg', fallback: 'B' },
  { id: '2', name: 'Fred', email: 'fred@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg', fallback: 'F' },
  { id: '3', name: 'Martha', email: 'martha@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg', fallback: 'M' },
]
</script>

<style lang="less">
.demo-list-box-controlled {
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 1rem;

  p {
    margin: 0;
    color: var(--color-muted);
    font-size: 0.875rem;
  }
}

.demo-list-box-surface {
  width: 16rem;
  border-radius: 1.5rem;
  box-shadow: var(--shadow-surface);
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}

.demo-list-box-check {
  width: 1rem;
  height: 1rem;
  color: var(--color-accent);
}
</style>

Custom Render Function

<template>
  <ListBox aria-label="Users" class="demo-list-box" data-custom="true" selection-mode="single">
    <ListBoxItem v-for="user in users" :id="user.id" :key="user.id" data-custom="item" :text-value="user.name">
      <Avatar size="sm">
        <AvatarImage :alt="user.name" :src="user.avatar" />
        <AvatarFallback>{{ user.fallback }}</AvatarFallback>
      </Avatar>
      <div class="demo-list-box-user">
        <Label>{{ user.name }}</Label>
        <Description>{{ user.email }}</Description>
      </div>
      <ListBoxItemIndicator />
    </ListBoxItem>
  </ListBox>
</template>

<script setup lang="ts">
import { Avatar, AvatarFallback, AvatarImage, Description, Label, ListBox, ListBoxItem, ListBoxItemIndicator } from '@heroui-vue/vue'

const users = [
  { id: '1', name: 'Bob', email: 'bob@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg', fallback: 'B' },
  { id: '2', name: 'Fred', email: 'fred@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg', fallback: 'F' },
  { id: '3', name: 'Martha', email: 'martha@heroui.com', avatar: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg', fallback: 'M' },
]
</script>

<style lang="less">
.demo-list-box {
  width: 13.75rem;
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}
</style>

Virtualization

The Vue version currently shows the same large-list interaction shape with a scrollable list. A true virtualization adapter still needs to be added before claiming parity with React Aria Virtualizer.

<template>
  <ListBox aria-label="Large user list" class="demo-list-box-virtualized" selection-mode="single">
    <ListBoxItem v-for="user in users" :id="user.id" :key="user.id" :text-value="user.name">
      <div class="demo-list-box-user">
        <Label>{{ user.name }}</Label>
        <Description>{{ user.email }}</Description>
      </div>
      <ListBoxItemIndicator />
    </ListBoxItem>
  </ListBox>
</template>

<script setup lang="ts">
import { Description, Label, ListBox, ListBoxItem, ListBoxItemIndicator } from '@heroui-vue/vue'

const firstNames = [
  'Emma',
  'Liam',
  'Olivia',
  'Noah',
  'Ava',
  'James',
  'Sophia',
  'Oliver',
  'Isabella',
  'Lucas',
  'Mia',
  'Ethan',
  'Charlotte',
  'Mason',
  'Amelia',
  'Logan',
  'Harper',
  'Alexander',
  'Ella',
  'Benjamin',
]
const lastNames = [
  'Smith',
  'Johnson',
  'Williams',
  'Brown',
  'Jones',
  'Garcia',
  'Miller',
  'Davis',
  'Rodriguez',
  'Martinez',
  'Anderson',
  'Taylor',
  'Thomas',
  'Jackson',
  'White',
  'Harris',
  'Clark',
  'Lewis',
  'Robinson',
  'Walker',
]
const users = Array.from({ length: 1000 }, (_, index) => {
  const firstName = firstNames[index % firstNames.length]
  const lastName = lastNames[Math.floor(index / firstNames.length) % lastNames.length]
  const name = `${firstName} ${lastName}`

  return {
    email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`,
    id: index + 1,
    name,
  }
})
</script>

<style lang="less">
.demo-list-box-virtualized {
  width: 18.75rem;
  height: 25rem;
  overflow-y: auto;
}

.demo-list-box-user {
  display: flex;
  flex-direction: column;
}
</style>

Autocomplete
ComboBox
Select

Styling

Use component props for selection, disabled state, and variants first. Demo-only layout classes are kept in the demo source so the preview code remains complete.

API

ListBox Props

Prop	Type	Default	Description
`ariaLabel`	`string`	`undefined`	Accessibility label for the listbox
`selectionMode`	`'none' \| 'single' \| 'multiple'`	`'single'`	Selection behavior
`selectedKeys`	`Array<string \| number>`	`undefined`	Controlled selected keys
`defaultSelectedKeys`	`Array<string \| number>`	`[]`	Initial selected keys
`disabledKeys`	`Array<string \| number>`	`[]`	Disabled item keys
`disabled` / `isDisabled`	`boolean`	`false`	Disables the whole listbox
`variant`	`'default' \| 'danger'`	`'default'`	Visual variant inherited by items

ListBoxItem Props

Prop	Type	Default	Description
`id` / `value`	`string \| number`	`undefined`	Unique item key
`textValue`	`string`	`undefined`	Text value used for accessible naming
`disabled` / `isDisabled`	`boolean`	`false`	Disables the item
`variant`	`'default' \| 'danger'`	inherited	Item variant

Events

Event	Payload	Description
`update:selectedKeys`	`Array<string \| number>`	Emitted when selection changes
`selection-change`	`Array<string \| number>`	Emitted when selection changes
`action`	`string \| number`	Emitted when an enabled item is activated

ListBox ​

Import ​

Usage ​

Anatomy ​

With Sections ​

Multi Select ​

With Disabled Items ​

Custom Check Icon ​

Controlled ​

Custom Render Function ​

Virtualization ​

Related Components ​

Styling ​

API ​

ListBox Props ​

ListBoxItem Props ​

Events ​