# Select
Picks one value from a list in a popup.
Source: [select.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/select.tsx)
```tsx
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
const priorities = {
urgent: "Urgent",
high: "High",
medium: "Medium",
low: "Low",
};
export default function SelectBasic() {
return (
);
}
```
## Installation
Add the registry, once per project:
```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```
Then add the component:
```bash
npx shadcn@latest add @jarvis/select
```
## Usage
```tsx
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
const fruits = {
apple: "Apple",
banana: "Banana",
cherry: "Cherry",
};
export function FruitSelect() {
return (
);
}
```
Pass `items` to `Select`, as an object of labels keyed by value or an array of `{ value, label }`,
so `SelectValue` can show the selected label.
For a long list people will want to search, use a [Combobox](https://ui.jarv.is/components/combobox.md). For the platform's
own picker, use a [Native Select](https://ui.jarv.is/components/native-select.md).
## Composition
- `Select`
- `SelectTrigger`
- `SelectValue`
- `SelectContent`
- `SelectItem`
- `SelectGroup`
- `SelectLabel`
- `SelectSeparator`
## Examples
### With a label
A `FieldLabel` in the same `Field` names the trigger. Without one, give the trigger an
`aria-label`.
```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
const languages = { en: "English", es: "Español", fr: "Français", de: "Deutsch" };
export default function SelectWithLabel() {
return (
LanguageUsed for emails and the interface.
);
}
```
### Groups
Use `SelectGroup`, `SelectLabel` and `SelectSeparator`.
```tsx
import * as React from "react";
import {
Select,
SelectContent,
SelectGroup,
SelectItem,
SelectLabel,
SelectSeparator,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
const timezones = [
{
region: "Americas",
zones: [
{ value: "america-los-angeles", label: "Pacific Time" },
{ value: "america-denver", label: "Mountain Time" },
{ value: "america-chicago", label: "Central Time" },
{ value: "america-new-york", label: "Eastern Time" },
],
},
{
region: "Europe",
zones: [
{ value: "europe-london", label: "London" },
{ value: "europe-berlin", label: "Berlin" },
{ value: "europe-helsinki", label: "Helsinki" },
],
},
{
region: "Asia Pacific",
zones: [
{ value: "asia-singapore", label: "Singapore" },
{ value: "asia-tokyo", label: "Tokyo" },
{ value: "australia-sydney", label: "Sydney" },
],
},
];
const items = timezones.flatMap((group) => group.zones);
export default function SelectGroups() {
return (
);
}
```
### Custom item content
Items can hold more than text. Pass `SelectValue` a function to render the selected item.
```tsx
import * as React from "react";
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
import { cn } from "@/lib/utils";
/* Card marks from Simple Icons (https://simpleicons.org), CC0. */
function VisaMark(props: React.ComponentProps<"svg">) {
return (
);
}
function AmexMark(props: React.ComponentProps<"svg">) {
return (
);
}
const paymentMethods = [
{ value: "visa", label: "Visa •• 7391", brand: "Visa", last4: "7391", expires: "11/27" },
{ value: "amex", label: "Amex •• 1008", brand: "Amex", last4: "1008", expires: "04/28" },
];
function CardBrand({ value }: { value: string }) {
const method = paymentMethods.find((item) => item.value === value);
if (!method) return null;
return (
{method.value === "amex" ? (
) : (
)}
);
}
export default function SelectPaymentMethod() {
return (
);
}
```
### Sizes
```tsx
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
const sortOptions = {
updated: "Last updated",
created: "Date created",
name: "Name",
};
export default function SelectSizes() {
return (
{(["sm", "default", "lg"] as const).map((size) => (
))}
);
}
```
### Disabled
Set `disabled` on `Select`, or on a single `SelectItem`.
```tsx
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
const sortOptions = {
updated: "Last updated",
created: "Date created",
name: "Name",
};
export default function SelectDisabled() {
return (
);
}
```
### Invalid
Set `invalid` on the `Field` and explain the problem with a `FieldError`.
```tsx
import { Field, FieldError, FieldLabel } from "@/components/ui/field";
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
const priorities = {
urgent: "Urgent",
high: "High",
medium: "Medium",
low: "Low",
};
export default function SelectInvalid() {
return (
PriorityChoose a priority.
);
}
```
## Props
`SelectContent` takes `side`, `sideOffset`, `align`, `alignOffset` and `alignItemWithTrigger`.
| Part | Extends |
| --- | --- |
| `Select` | [`Select.Root`](https://base-ui.com/react/components/select#root) |
| `SelectGroup` | [`Select.Group`](https://base-ui.com/react/components/select#group) |
| `SelectValue` | [`Select.Value`](https://base-ui.com/react/components/select#value) |
| `SelectTrigger` | [`Select.Trigger`](https://base-ui.com/react/components/select#trigger) |
| `SelectContent` | [`Select.Popup`](https://base-ui.com/react/components/select#popup) |
| `SelectLabel` | [`Select.GroupLabel`](https://base-ui.com/react/components/select#grouplabel) |
| `SelectItem` | [`Select.Item`](https://base-ui.com/react/components/select#item) |
| `SelectSeparator` | [`Select.Separator`](https://base-ui.com/react/components/select#separator) |
| `SelectScrollUpButton` | [`Select.ScrollUpArrow`](https://base-ui.com/react/components/select#scrolluparrow) |
| `SelectScrollDownButton` | [`Select.ScrollDownArrow`](https://base-ui.com/react/components/select#scrolldownarrow) |
The tables leave out `className`, `style` and `render`. Parts built on Base UI take them as its [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides describe.
### Select
| Prop | Type | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children?` | `React.ReactNode` | |
| `inputRef?` | `React.Ref` | A ref to access the hidden input element. |
| `name?` | `string` | Identifies the field when a form is submitted. |
| `form?` | `string` | Identifies the form that owns the hidden input. Useful when the select is rendered outside the form. |
| `autoComplete?` | `string` | Provides a hint to the browser for autofill. |
| `id?` | `string` | The id of the Select. |
| `required?` | `boolean` | Whether the user must choose a value before submitting a form. Default: `false` |
| `readOnly?` | `boolean` | Whether the user should be unable to choose a different option from the select popup. Default: `false` |
| `disabled?` | `boolean` | Whether the component should ignore user interaction. Default: `false` |
| `multiple?` | `boolean` | Whether multiple items can be selected. Default: `false` |
| `highlightItemOnHover?` | `boolean` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. Default: `true` |
| `defaultOpen?` | `boolean` | Whether the select popup is initially open. To render a controlled select popup, use the `open` prop instead. Default: `false` |
| `onOpenChange?` | `((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)` | Event handler called when the select popup is opened or closed. |
| `onOpenChangeComplete?` | `((open: boolean) => void)` | Event handler called after any animations complete when the select popup is opened or closed. |
| `open?` | `boolean` | Whether the select popup is currently open. |
| `modal?` | `boolean` | Determines if the select enters a modal state when open. - `true`: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. Default: `true` |
| `actionsRef?` | `React.RefObject` | A ref to imperative actions. - `unmount`: Ends the closing phase of the select after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the select completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. - `close`: Closes the select imperatively when called. |
| `items?` | `readonly Group[] \| readonly { label: React.ReactNode; value: any; }[] \| Record` | Data structure of the items rendered in the select popup. When specified, `` renders the label of the selected item instead of the raw value. |
| `itemToStringLabel?` | `((itemValue: unknown) => string)` | When the item values are objects (``), this function converts the object value to a string representation for display in the trigger. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. |
| `itemToStringValue?` | `((itemValue: unknown) => string)` | When the item values are objects (``), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop. |
| `isItemEqualToValue?` | `((itemValue: unknown, value: unknown) => boolean)` | Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison. |
| `defaultValue?` | `unknown` | The uncontrolled value of the select when it's initially rendered. To render a controlled select, use the `value` prop instead. |
| `value?` | `unknown` | The value of the select. Use when controlled. |
| `onValueChange?` | `((value: unknown, eventDetails: SelectRootChangeEventDetails) => void)` | Event handler called when the value of the select changes. |
### SelectValue
| Prop | Type | Description |
| -------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children?` | `((value: any) => React.ReactNode) \| React.ReactNode` | Accepts a function that returns a `ReactNode` to format the selected value. Treat the value as read-only: in `multiple` mode it may be a shared frozen array when nothing is selected. |
| `placeholder?` | `React.ReactNode` | The placeholder value to display when no value is selected. This is overridden by `children` if specified, or by a null item's label in `items`. |
### SelectTrigger
| Prop | Type | Description |
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children?` | `React.ReactNode` | |
| `disabled?` | `boolean` | Whether the component should ignore user interaction. |
| `nativeButton?` | `boolean` | Whether the component renders a native `