UI

Select

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

Read Markdown

Web 0.2.1

  • Defaultlight7.93 : 1AA 4.5dark9.07 : 1AA 4.5
  • KeyboardEnterArrowDownArrowUpEscape
  • measured on 0.2.1
npx shadcn@latest add @maeso/select
Size
68.8 kB gzipmeasured on 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.

{
  "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.

npx shadcn@latest add @maeso/maeso
@import "./styles/theme.web.css";
npx shadcn@latest add @maeso/select

Props

Select

PropTypeRequiredDescription
aria-labelstring | undefinedno
defaultValuestring | undefinedno
disabledboolean | undefinedno
errorReactNodeno
hintReactNodeno
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" | undefinednoA glyph before the value, naming what the choice is about.
idstring | undefinedno
labelReactNodeno
namestring | undefinednoNames the hidden native control a surrounding form submits.
onChange((value: string) => void) | undefinednoThe value of the option the reader chose.
onOpenChange((open: boolean) => void) | undefinednoRefreshes choices when opening without putting actions inside the list.
optionsreadonly SelectOption[] | undefinedno
placeholderstring | undefinednoDrawn in the muted ink while nothing is chosen.
requiredboolean | undefinedno
sizeControlSize | undefinedno
styleCSSProperties | undefinedno
valuestring | undefinedno
Also accepts 3 inherited props
PropTypeRequiredDescription
aria-describedbystring | undefinednoIdentifies the element (or elements) that describes the object.
aria-invalid"false" | "grammar" | "spelling" | "true" | boolean | undefinednoIndicates the entered value does not conform to the format expected by the application.
aria-labelledbystring | undefinednoIdentifies the element (or elements) that labels the current element.

Proof

Contrast

measured on 0.2.1

StateForegroundBackgroundRatioFloor
defaultrgb(67 77 86)rgb(248 245 240)7.93AA 4.5
default (dark)rgb(181 182 182)rgb(7 21 34)9.07AA 4.5

Keyboard

measured on 0.2.1

KeyAction
EnterOpen list and commit focused selection
ArrowDownMove to next option
ArrowUpMove to previous option
EscapeDismiss 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

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;

not on native yet