# Select

A field-shaped select with a labelled trigger and a floating option list.

## Web 0.2.1

### Usage

Supply the available choices, selected value and change handler. Keep the choice labels understandable outside their surrounding sentence.

### Accessibility

Give the trigger a visible label. Preserve arrow-key navigation and the selected option's announcement.

### When to use

Use when one value must come from a known list. Use Combobox when searching the list is useful.

### Install

Add this registry to your project's components.json once, before the first install. Keep your existing settings and other registries.

```json
{
  "registries": {
    "@maeso": "http://127.0.0.1:4321/r/{name}.json"
  }
}
```

Then install the registry's default theme once, and import its sheet in the CSS entry that imports Tailwind. It paints every item from this registry.

```sh
npx shadcn@latest add @maeso/maeso
```

```css
@import "./styles/theme.web.css";
```

```sh
npx shadcn@latest add @maeso/select
```

### Props

#### Select

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| aria-label | string \| undefined | no |  |
| defaultValue | string \| undefined | no |  |
| disabled | boolean \| undefined | no |  |
| error | ReactNode | no |  |
| hint | ReactNode | no |  |
| iconLeft | "activity" \| "adjustments-horizontal" \| "alert-triangle" \| "app-window" \| "arrow-down" \| "arrow-left" \| "arrow-right" \| "arrow-up" \| "arrow-up-right" \| "arrows-diagonal" \| "arrows-diagonal-minimize-2" \| "at" \| "award" \| "bell" \| "calendar" \| "check" \| "chevron-down" \| "chevron-left" \| "chevron-right" \| "chevron-up" \| "circle" \| "circle-check" \| "circle-dashed" \| "circle-dot" \| "circle-help" \| "circle-pause" \| "circle-play" \| "circle-slash" \| "click" \| "clipboard-check" \| "clock" \| "compass" \| "copy" \| "corner-down-right" \| "corner-up-left" \| "cpu" \| "device-mobile" \| "device-tablet" \| "dots" \| "download" \| "eraser" \| "external-link" \| "eye" \| "file" \| "file-pen" \| "file-plus" \| "file-text" \| "folder" \| "git-branch" \| "globe" \| "grip-vertical" \| "history" \| "inbox" \| "info" \| "info-circle" \| "keyboard" \| "layout-grid" \| "link" \| "list" \| "list-checks" \| "lock" \| "log-out" \| "marquee-2" \| "message-2" \| "message-square" \| "minus" \| "monitor" \| "moon" \| "note" \| "octagon-x" \| "panel-left-close" \| "panel-left-open" \| "paperclip" \| "pencil" \| "play" \| "plug" \| "plus" \| "pointer" \| "refresh-cw" \| "rotate-cw" \| "route" \| "scale" \| "search" \| "settings" \| "shield-check" \| "slash" \| "square" \| "square-half" \| "sun" \| "terminal-2" \| "trash" \| "triangle-alert" \| "unplug" \| "upload" \| "user" \| "user-round" \| "user-round-check" \| "users" \| "wallet" \| "workflow" \| "wrap-text" \| "x" \| undefined | no | A glyph before the value, naming what the choice is about. |
| id | string \| undefined | no |  |
| label | ReactNode | no |  |
| name | string \| undefined | no | Names the hidden native control a surrounding form submits. |
| onChange | ((value: string) => void) \| undefined | no | The value of the option the reader chose. |
| onOpenChange | ((open: boolean) => void) \| undefined | no | Refreshes choices when opening without putting actions inside the list. |
| options | readonly SelectOption[] \| undefined | no |  |
| placeholder | string \| undefined | no | Drawn in the muted ink while nothing is chosen. |
| required | boolean \| undefined | no |  |
| size | ControlSize \| undefined | no |  |
| style | CSSProperties \| undefined | no |  |
| value | string \| undefined | no |  |

##### Inherited

Also accepts 3 inherited props

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| aria-describedby | string \| undefined | no | Identifies the element (or elements) that describes the object. |
| aria-invalid | "false" \| "grammar" \| "spelling" \| "true" \| boolean \| undefined | no | Indicates the entered value does not conform to the format expected by the application. |
| aria-labelledby | string \| undefined | no | Identifies the element (or elements) that labels the current element. |

### Proof

#### Contrast

measured on 0.2.1

| State | Foreground | Background | Ratio | Floor |
| --- | --- | --- | --- | --- |
| default | rgb(67 77 86) | rgb(248 245 240) | 7.93 | AA 4.5 |
| default (dark) | rgb(181 182 182) | rgb(7 21 34) | 9.07 | AA 4.5 |

#### Keyboard

measured on 0.2.1

| Key | Action |
| --- | --- |
| Enter | Open list and commit focused selection |
| ArrowDown | Move to next option |
| ArrowUp | Move to previous option |
| Escape | Dismiss list without changing selection |

#### Size

68778 gzip bytes · measured on 0.2.1

### Motion

The option list enters below the field.

Configured duration: 200 ms

Reduced motion: none

#### Motion timing

Observed duration: 200 ms · measured on 0.2.1

#### Reduced motion

passed · measured on 0.2.1

### Example

```tsx
import { Select } from "@/components/ui/_kit/forms/select/Select";

const Example = () => (
		<Select
			label="Project"
			defaultValue="atlas"
			options={[
				{
					value: "atlas",
					label: "Atlas project with a long selected value that must stay on one line",
				},
				{ value: "harbor", label: "Harbor" },
				{ value: "meridian", label: "Meridian" },
			]}
		/>
	);
export default Example;
```

### Preview · 0.2.1

not on native yet
