# NativeSelect

> A styled native <select> for simple choices and long lists.

Category: Forms · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/native-select

NativeSelect keeps the operating system picker, which is the most usable option on phones and works without JavaScript. Use it for straightforward single choices such as country, role or time zone. Use Select when options need icons, descriptions or custom rendering, and Combobox when users need to type to filter.

## Import

```tsx
import { NativeSelect, FormField } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { FormField, NativeSelect } from '@bindshq/stance-react';

export function Basic() {
  return (
    <div style={{ width: '100%', maxWidth: 320 }}>
      <FormField label="Role">
        <NativeSelect
          placeholder="Choose a role"
          options={[
            { value: 'owner', label: 'Owner' },
            { value: 'admin', label: 'Admin' },
            { value: 'member', label: 'Member' },
            { value: 'viewer', label: 'Viewer (read only)' },
          ]}
        />
      </FormField>
    </div>
  );
}
```

### Option groups

```tsx
import { FormField, NativeSelect } from '@bindshq/stance-react';

export function Groups() {
  return (
    <div style={{ width: '100%', maxWidth: 320 }}>
      <FormField label="Time zone">
        <NativeSelect defaultValue="Europe/London">
          <optgroup label="Europe">
            <option value="Europe/London">London (GMT)</option>
            <option value="Europe/Berlin">Berlin (CET)</option>
          </optgroup>
          <optgroup label="Asia">
            <option value="Asia/Kolkata">Kolkata (IST)</option>
            <option value="Asia/Singapore">Singapore (SGT)</option>
          </optgroup>
        </NativeSelect>
      </FormField>
    </div>
  );
}
```

### Sizes and states

```tsx
import { FormField, NativeSelect } from '@bindshq/stance-react';

export function States() {
  const options = [
    { value: 'monthly', label: 'Monthly' },
    { value: 'annual', label: 'Annual' },
  ];
  return (
    <div style={{ display: 'grid', gap: 12, width: '100%', maxWidth: 320 }}>
      <NativeSelect size="sm" aria-label="Billing (small)" options={options} />
      <FormField label="Billing cycle" error="Choose a billing cycle">
        <NativeSelect placeholder="Select…" options={options} />
      </FormField>
      <FormField label="Plan" disabled>
        <NativeSelect options={[{ value: 'team', label: 'Team' }]} />
      </FormField>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| NativeSelect | `options` | `NativeSelectOption[]` | None | Options as data: { value, label, disabled? }. Or pass <option> children. |
| NativeSelect | `placeholder` | `string` | None | Adds a disabled empty first option, selected by default. |
| NativeSelect | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |
| NativeSelect | `invalid` | `boolean` | None | Marks the field invalid. |
| NativeSelect | `wrapperClassName` | `string` | None | Class for the outer field box. |
| NativeSelect | `...props` | `SelectHTMLAttributes` | None | Native select attributes. |

## Accessibility

- Uses the native element, so screen reader and keyboard support come from the platform.
- Integrates with FormField for label, description and error.
- Avoid an empty placeholder as the only label; always provide a visible label.

## Keyboard

| Keys | Action |
| --- | --- |
| `Space` `Enter` `Alt+ArrowDown` | Opens the picker (platform dependent). |
| `ArrowUp` `ArrowDown` | Changes the selection. |
| `Type a character` | Jumps to matching options. |

## Related

- https://stanceui.com/components/select
- https://stanceui.com/components/combobox