# Listbox
## Summary
`Listbox` is an always visible list to choose one or several options from, like a native `select` with `size`. The focus stays on the list, which points to the active option with `aria-activedescendant`.
## Imports
```tsx
import { Listbox, ListboxGroup, ListboxOption, type ListboxGroupProps, type ListboxOptionProps, type ListboxProps, type ListboxValue } from '@vega-ui/react';
```
## Exported Types
- `ListboxProps`
- `ListboxOptionProps`
- `ListboxGroupProps`
- `ListboxValue`
## Basic Usage
```tsx
import { Listbox, ListboxOption } from '@vega-ui/react';
export default function BasicUsage() {
return (
Pickup pointCourier to the doorParcel locker
);
}
```
## Variants
- Selection: one value, or an array with `multiple`
- Size: `xs`, `sm`, `md`, `lg`, `xl`
- Content: plain text, or markup with `label` for typeahead
## Edge Cases
- `value={null}` clears a controlled single list, while `undefined` makes it uncontrolled.
- A disabled list disables all its options, whatever their own `disabled` is.
- Options are read from the DOM on each key press, so filtering and adding them needs no registration.
- The height is plain CSS on the list, which scrolls by itself.
## Common Mistakes
- Leaving the list without `aria-label` or `aria-labelledby`.
- Giving two options the same `value`.
- Using `Listbox` for a compact form field, where [Select](https://vega-ui.dev/components/select/) fits better.
## Examples
### Basic
#### Basic: visible label
The list is always visible, so it usually sits under a visible heading. `aria-labelledby` points at that text and gives the list its accessible name; options are rendered from data.
```tsx
import { Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useId } from 'react';
const layouts = [
{ value: 'board', label: 'Board' },
{ value: 'list', label: 'List' },
{ value: 'timeline', label: 'Timeline' },
{ value: 'calendar', label: 'Calendar' },
];
export default function VisibleLabel() {
const labelId = useId();
return (
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: value with a reset
The parent owns the font and the preview below reads it. The reset sets `null`, which clears a controlled single list; `undefined` would make it uncontrolled.
```tsx
import { Button, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useState } from 'react';
const fonts = [
{ value: 'serif', label: 'Serif', family: 'Georgia, serif' },
{ value: 'sans', label: 'Sans-serif', family: 'system-ui, sans-serif' },
{ value: 'mono', label: 'Monospace', family: 'ui-monospace, monospace' },
];
export default function ValueWithAReset() {
const [font, setFont] = useState('serif');
const current = fonts.find((item) => item.value === font);
return (
setFont(next ?? null)} style={{ border: '1px solid var(--separator-opaque)' }}>
{fonts.map((item) => (
{item.label}
))}
The quick brown fox jumps over the lazy dog.
);
}
```
#### Controlled/Stateful: several choices
With `multiple` the value is an array. The parent derives the count and the extra price from it, and clears it with an empty array.
```tsx
import { Button, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useState } from 'react';
const toppings = [
{ value: 'cheese', label: 'Extra mozzarella', price: 1.5 },
{ value: 'mushrooms', label: 'Mushrooms', price: 1 },
{ value: 'olives', label: 'Black olives', price: 1 },
{ value: 'pepperoni', label: 'Pepperoni', price: 2 },
{ value: 'jalapenos', label: 'Jalapeños', price: 0.5 },
];
export default function SeveralChoices() {
const [selected, setSelected] = useState(['cheese']);
const total = toppings
.filter((item) => selected.includes(item.value))
.reduce((sum, item) => sum + item.price, 0);
return (
{toppings.map((item) => (
{item.label}
))}
{selected.length} selected · +${total.toFixed(2)}
);
}
```
### Form/Integration
#### Form/Integration: submitting the selection with a form
`Listbox` is not a form field, so the form reads hidden inputs rendered from the same state, one per selected value. The form's `onReset` restores the initial selection.
```tsx
import { Button, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
const initialChannels = ['email'];
export default function ListboxInForm() {
const labelId = useId();
const [channels, setChannels] = useState(initialChannels);
const [submitted, setSubmitted] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSubmitted(data.getAll('channel').join(', ') || 'nothing');
};
const onReset = () => {
setChannels(initialChannels);
setSubmitted('');
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: groups and a scrolling list
`ListboxGroup` groups airports by country and is named by its heading through `aria-labelledby`. The list height is plain CSS: it scrolls by itself and keeps the active option in view while you move with the arrow keys.
```tsx
import { Listbox, ListboxGroup, ListboxOption, Text } from '@vega-ui/react';
import { useId } from 'react';
const countries = [
{
name: 'France',
airports: [
{ code: 'CDG', name: 'Paris Charles de Gaulle' },
{ code: 'ORY', name: 'Paris Orly' },
{ code: 'NCE', name: 'Nice Côte d’Azur' },
{ code: 'LYS', name: 'Lyon Saint-Exupéry' },
],
},
{
name: 'Germany',
airports: [
{ code: 'FRA', name: 'Frankfurt' },
{ code: 'MUC', name: 'Munich' },
{ code: 'BER', name: 'Berlin Brandenburg' },
],
},
{
name: 'Japan',
airports: [
{ code: 'HND', name: 'Tokyo Haneda' },
{ code: 'NRT', name: 'Tokyo Narita' },
{ code: 'KIX', name: 'Osaka Kansai' },
],
},
];
export default function GroupsAndAScrollingList() {
const id = useId();
return (
{countries.map((country) => (
{country.name}
{country.airports.map((airport) => (
{airport.name}
{airport.code}
))}
))}
);
}
```
### Error
#### Error: explain an empty required choice
The form checks the choice on submit, sets `aria-invalid` on the list and links the message with `aria-describedby`. Choosing a plan clears the error.
```tsx
import { Button, HelperText, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
export default function ExplainAnEmptyRequiredChoice() {
const id = useId();
const errorId = `${id}-error`;
const [plan, setPlan] = useState(null);
const [invalid, setInvalid] = useState(false);
const [done, setDone] = useState(false);
const onChangeValue = (next: string | undefined) => {
setPlan(next ?? null);
setInvalid(false);
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
if (plan === null) {
setInvalid(true);
return;
}
setDone(true);
};
return (
);
}
```
### Disabled
#### Disabled: options that cannot be chosen
Sold-out sizes stay visible with their reason but are disabled: clicks ignore them and arrow keys skip them.
```tsx
import { Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useId } from 'react';
const sizes = [
{ value: 'xs', label: 'XS', stock: 0 },
{ value: 's', label: 'S', stock: 4 },
{ value: 'm', label: 'M', stock: 12 },
{ value: 'l', label: 'L', stock: 0 },
{ value: 'xl', label: 'XL', stock: 2 },
];
export default function DisabledOptions() {
const id = useId();
return (