# Option
## Summary
`Option` is the presentational selectable-row primitive reused by list-like controls. It is a `div` with `role='option'` and selected, active, size, and disabled states, but it does not manage selection logic by itself. For a working list use [Listbox](https://vega-ui.dev/components/listbox/) or [Select](https://vega-ui.dev/components/select/).
## Imports
```tsx
import { Option, type OptionProps, type OptionSize } from '@vega-ui/react';
```
## Exported Types
- `OptionProps`
- `OptionSize`
## Basic Usage
```tsx
import { Option } from '@vega-ui/react';
export default function BasicUsage() {
return (
);
}
```
## Variants
- Size: `xs`, `sm`, `md`, `lg`, `xl`
- State: selected, active, disabled
- Content: plain label or richer icon/text row
## Edge Cases
- `Option` is a UI primitive, not a full select or menu system.
- A disabled `Option` does not call `onClick`.
- Parent controls still need to own active, selected, and keyboard navigation logic coherently.
## Common Mistakes
- Using `Option` alone and expecting selection state management.
- Mixing `Option` size with a parent field size that does not match.
- Forgetting to coordinate `selected` and visible active state in the parent system.
## Examples
### Basic
#### Basic: rows inside a named list
`Option` renders a row with `role='option'`, so it always goes inside an element with `role='listbox'` and an accessible name. `selected` only paints and announces the state; it does not manage it.
```tsx
import { Option } from '@vega-ui/react';
export default function BasicUsage() {
return (
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: selected state from parent
A custom list owns both states: `selected` follows a click or Enter, `active` follows the arrow keys. The focus stays on the list, which points at the active row with `aria-activedescendant`, so every row needs an `id`.
```tsx
import { Option, Text } from '@vega-ui/react';
import { KeyboardEvent, useId, useState } from 'react';
const statuses = [
{ value: 'backlog', label: 'Backlog' },
{ value: 'progress', label: 'In progress' },
{ value: 'review', label: 'In review' },
{ value: 'done', label: 'Done' },
];
export default function SelectedStateFromParent() {
const id = useId();
const [selected, setSelected] = useState('review');
const [active, setActive] = useState(null);
const current = statuses.find((status) => status.value === selected);
const moveActive = (step: number) => {
const index = statuses.findIndex((status) => status.value === active);
const next = Math.min(Math.max(index + step, 0), statuses.length - 1);
setActive(statuses[next].value);
};
const onKeyDown = (event: KeyboardEvent) => {
if (event.key === 'ArrowDown') {
event.preventDefault();
moveActive(1);
return;
}
if (event.key === 'ArrowUp') {
event.preventDefault();
moveActive(-1);
return;
}
if (event.key !== 'Enter' && event.key !== ' ') return;
if (active === null) return;
event.preventDefault();
setSelected(active);
};
return (
);
}
```
### Form/Integration
#### Form/Integration: suggestions for a text field
The text field is the combobox and keeps the focus: it points at the active suggestion with `aria-activedescendant`, and Enter or a click copies the name into the field, which the form submits as `assignee`. `onMouseDown` prevents the row from taking the focus away from the field.
```tsx
import { Button, Label, Option, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, KeyboardEvent, useId, useState } from 'react';
const people = ['Amara Okafor', 'Boris Petrov', 'Chloé Lefèvre', 'Dmitri Volkov', 'Elena Rossi', 'Farah Haddad'];
export default function OptionInCustomSelectorList() {
const id = useId();
const listId = `${id}-list`;
const [query, setQuery] = useState('');
const [active, setActive] = useState(0);
const [submitted, setSubmitted] = useState('');
const matches = people.filter((person) => person.toLowerCase().includes(query.trim().toLowerCase()));
const open = query.trim() !== '' && !people.includes(query);
const choose = (person: string) => {
setQuery(person);
setActive(0);
};
const onKeyDown = (event: KeyboardEvent) => {
if (!open || matches.length === 0) return;
if (event.key === 'ArrowDown') {
event.preventDefault();
setActive(Math.min(active + 1, matches.length - 1));
return;
}
if (event.key === 'ArrowUp') {
event.preventDefault();
setActive(Math.max(active - 1, 0));
return;
}
if (event.key !== 'Enter') return;
event.preventDefault();
choose(matches[active]);
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
setSubmitted(String(new FormData(event.currentTarget).get('assignee')));
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: rich option content
Rows with an icon and a hint inside a raised panel. The row is still one selection surface; two-line content needs `height: 'auto'`, because the row height is fixed by size.
```tsx
import { Icon, Option, Text } from '@vega-ui/react';
import { CopyIcon, LinkIcon, MailIcon, Share2Icon } from '@vega-ui/icons';
const actions = [
{ value: 'link', label: 'Copy link', hint: 'Anyone with the link can view', icon: LinkIcon },
{ value: 'email', label: 'Send by email', hint: 'Up to 20 recipients', icon: MailIcon },
{ value: 'duplicate', label: 'Duplicate', hint: 'Creates a private copy', icon: CopyIcon },
{ value: 'export', label: 'Export to Drive', hint: 'PDF or DOCX', icon: Share2Icon },
];
export default function RichOptionContent() {
return (
{actions.map((action) => (
))}
);
}
```
### Disabled
#### Disabled: unavailable options with a reason
Disabled rows stay visible and ignore clicks. The reason is shown in the row and linked with `aria-describedby`, so a screen reader announces why the plan cannot be chosen.
```tsx
import { Option } from '@vega-ui/react';
import { useId } from 'react';
const plans = [
{ value: 'starter', label: 'Starter', reason: '' },
{ value: 'team', label: 'Team', reason: '' },
{ value: 'legacy', label: 'Legacy Pro', reason: 'No longer available for new workspaces' },
{ value: 'enterprise', label: 'Enterprise', reason: 'Requires a sales contract' },
];
export default function UnavailablePlanHint() {
const id = useId();
return (
{plans.map((plan) => (
))}
);
}
```
### Edge
#### Edge: active but not selected row
`active` and `selected` are separate: the active row is where the keyboard is, the selected row is the value. Here "Newest first" is the value while the list points at "Oldest first".
```tsx
import { Option } from '@vega-ui/react';
import { useId } from 'react';
export default function ActiveButNotSelectedRow() {
const id = useId();
return (
);
}
```
#### Edge: long labels in a narrow list
Rows have a fixed height, so long text has to be truncated inside the row. The full path stays available in `title`.
```tsx
import { Option } from '@vega-ui/react';
const folders = [
'Inbox',
'Projects / 2026 / Northwind logistics / Contracts and signed amendments',
'Receipts',
'Archive / Customer support / Escalations that were resolved after the SLA deadline',
];
export default function LongLabel() {
return (
{folders.map((folder) => (
))}
);
}
```
## Anatomy
### Overview
`Option` is a single-part primitive that renders a `div` with `role='option'`.
### Required Parts
#### `Option`
Required. Owns the full option-row surface, sizing, and presentational states.
### Optional Parts
There are no exported child parts.
### Composition Order
1. `Option`
2. label and optional rich content
### Valid Composition Patterns
```tsx
import { Icon, Option, Text } from '@vega-ui/react';
import { CopyIcon, LinkIcon, MailIcon, Share2Icon } from '@vega-ui/icons';
const actions = [
{ value: 'link', label: 'Copy link', hint: 'Anyone with the link can view', icon: LinkIcon },
{ value: 'email', label: 'Send by email', hint: 'Up to 20 recipients', icon: MailIcon },
{ value: 'duplicate', label: 'Duplicate', hint: 'Creates a private copy', icon: CopyIcon },
{ value: 'export', label: 'Export to Drive', hint: 'PDF or DOCX', icon: Share2Icon },
];
export default function RichOptionContent() {
return (
{actions.map((action) => (
))}
);
}
```
Every `Option` sits inside an element with `role='listbox'` that has an accessible name. The content of a row can be an icon and two lines of text, but the row stays one selection surface; rows with more than one line need `height: 'auto'`.
### Invalid Composition Patterns
#### Option used as a standalone selector without parent state
The row renders, but selection semantics are incomplete.
#### Complex nested interactive controls inside one option
The option row should remain one coherent selection surface.