# Option Guides

## Patterns

### Rich Selector Row

When to use:

- an option needs iconography or secondary visual context

Composition notes:

- keep the row a single selection surface

Trade-offs:

- scanable and expressive
- more complex than plain text rows

```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 (
    <div
      role='listbox'
      aria-label='Share options'
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 'var(--spacing-3)',
        padding: 'var(--spacing-4)',
        width: '100%',
        maxWidth: 300,
        boxSizing: 'border-box',
        borderRadius: 'var(--spacing-8)',
        background: 'var(--surface-secondary)',
        border: '1px solid var(--separator-opaque)',
        boxShadow: 'var(--surface-shadow)',
      }}
    >
      {actions.map((action) => (
        <Option
          key={action.value}
          selected={action.value === 'link'}
          style={{ height: 'auto', paddingBlock: 'var(--spacing-5)', gap: 'var(--spacing-8)' }}
        >
          <Icon size='sm'>
            <action.icon />
          </Icon>
          <span style={{ display: 'flex', flexDirection: 'column' }}>
            <Text size={3}>{action.label}</Text>
            <Text size={2} style={{ opacity: 0.75 }}>{action.hint}</Text>
          </span>
        </Option>
      ))}
    </div>
  );
}
```

### Parent-Owned Selection

When to use:

- the list state lives in a custom parent control

Composition notes:

- derive `selected` and click handlers from the parent state
- keep keyboard behavior on the list: it holds the focus and points at the active row with `aria-activedescendant`

Trade-offs:

- flexible
- requires a real parent selection model

```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<string | null>(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<HTMLDivElement>) => {
    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 (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-4)', width: '100%', maxWidth: 260 }}>
      <div
        role='listbox'
        tabIndex={0}
        aria-label='Issue status'
        aria-activedescendant={active === null ? undefined : `${id}-${active}`}
        onKeyDown={onKeyDown}
        onFocus={() => setActive(selected)}
        onBlur={() => setActive(null)}
        style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-3)', padding: 'var(--spacing-4)', borderRadius: 'var(--spacing-8)', background: 'var(--surface-secondary)', border: '1px solid var(--separator-opaque)', boxSizing: 'border-box' }}
      >
        {statuses.map((status) => (
          <Option
            key={status.value}
            id={`${id}-${status.value}`}
            selected={status.value === selected}
            active={status.value === active}
            onClick={() => setSelected(status.value)}
          >
            {status.label}
          </Option>
        ))}
      </div>
      <Text size={2} style={{ color: 'var(--label-secondary)' }}>Status: {current?.label}</Text>
    </div>
  );
}
```

### Disabled Business State

When to use:

- an option is visible but unavailable

Composition notes:

- keep the reason visible in the row and link it with `aria-describedby`
- leave the row non-interactive

Trade-offs:

- preserves discoverability
- unavailable options still need explanatory context

```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 (
    <div role='listbox' aria-label='Plan' style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-3)', width: '100%', maxWidth: 320, padding: 'var(--spacing-4)', borderRadius: 'var(--spacing-8)', background: 'var(--surface-secondary)', border: '1px solid var(--separator-opaque)', boxSizing: 'border-box' }}>
      {plans.map((plan) => (
        <Option
          key={plan.value}
          selected={plan.value === 'team'}
          disabled={plan.reason !== ''}
          aria-describedby={plan.reason === '' ? undefined : `${id}-${plan.value}`}
          style={plan.reason === '' ? undefined : { height: 'auto', paddingBlock: 'var(--spacing-5)' }}
        >
          <span style={{ display: 'flex', flexDirection: 'column' }}>
            {plan.label}
            {plan.reason !== '' && (
              <span id={`${id}-${plan.value}`} style={{ fontSize: 'var(--font-size-2)' }}>
                {plan.reason}
              </span>
            )}
          </span>
        </Option>
      ))}
    </div>
  );
}
```

## Comparison

### Quick Decision Rule

Use `Option` when building a list-like selector surface that should match VegaUI option styling. Use `Button` for generic actions and `SelectOption` when you already have a complete `Select` composition.

### `Option` vs `Button`

- Use `Option` for selectable list rows.
- Use `Button` for direct actions.

### `Option` vs `SelectOption`

- Use `Option` when building a custom selector primitive.
- Use `SelectOption` inside the full `Select` subsystem.

### Choose This Component When

- you need a reusable presentational option row
- the parent pattern already owns selection logic

### Do Not Choose This Component When

- you need a full selector system without extra work
- the row is really an action, not a selectable option

## Troubleshooting

### The Row Looks Selectable But Selection Does Not Persist

#### Symptom

Clicking the row changes nothing durable in the UI.

#### Likely Cause

`Option` was rendered without a parent selection model.

#### How To Verify

- inspect whether `selected` is driven from parent state

#### Fix

Move selection logic into the parent control and pass the resulting state into each option.

### The Keyboard Does Not Reach The Options

#### Symptom

The arrows do nothing and no option looks active.

#### Likely Cause

`Option` does not take focus or handle keys, and nothing owns the list.

#### How To Verify

- check that a parent has the focus, sets `aria-activedescendant`, and passes `active` to one option

#### Fix

Use [Listbox](https://vega-ui.dev/components/listbox/) or [Select](https://vega-ui.dev/components/select/), which do this for you.

### Disabled Rows Still Need Explanation

#### Symptom

Users can see a disabled option but do not know why it is unavailable.

#### Likely Cause

The row is disabled visually without surrounding explanatory copy.

#### How To Verify

- test the flow with a user who has not seen the business rule before

#### Fix

Keep the row disabled and surface the reason nearby through helper text or explanatory copy.