Select
Single-select dropdown built on Field, with keyboard navigation.
import { Select, SelectOption }from "@/components/ui"
Specification
Selects one option from a short, fixed list via a keyboard-navigable dropdown built on Field.
Props (9)
Every prop this component accepts, its type, default, and how to use it.
| Prop | Type | Default | Description |
|---|---|---|---|
| id | string | — | Explicit element id, wired to the label. |
| label | string | — | Visible field label shown above the control. |
| hint | string | — | Helper text shown below the field when there is no error. |
| error | string | — | Error message; renders the field in the error state. |
| disabled | boolean | — | Disables the select. |
| options* | SelectOption[] | — | Options to choose from; each has value, label and optional disabled. |
| value* | string | null | — | The value of the currently selected option, or null. |
| onChange* | (value: string) => void | — | Called with the selected option's value. |
| placeholder | string | "Select…" | Text shown when no option is selected. |
Roles
Full source
The complete component, read from
src/components/ui/select.tsx.select.tsx
"use client";
import { useRef, useState, useEffect, useId, type KeyboardEvent as ReactKeyboardEvent } from "react";
import { createPortal } from "react-dom";
import { Check, ChevronDown } from "lucide-react";
import { cn } from "@/lib/utils";
import { usePopoverPosition, useMounted } from "@/hooks";
import { Field, controlBase, controlClasses } from "./field";
export interface SelectOption {
value: string;
label: string;
disabled?: boolean;
}
interface SelectProps {
id?: string;
label?: string;
hint?: string;
error?: string;
disabled?: boolean;
options: SelectOption[];
value: string | null;
onChange: (value: string) => void;
placeholder?: string;
}
export function Select({
id,
label,
hint,
error,
disabled,
options,
value,
onChange,
placeholder = "Select…",
}: SelectProps) {
const [open, setOpen] = useState(false);
const [active, setActive] = useState(0);
const triggerRef = useRef<HTMLButtonElement>(null);
const listRef = useRef<HTMLDivElement>(null);
const position = usePopoverPosition(triggerRef, open, { matchWidth: true, preferredHeight: 260 });
const mounted = useMounted();
const reactId = useId();
const selectId = id ?? reactId;
const messageId = `${selectId}-message`;
const selected = options.find((o) => o.value === value) ?? null;
useEffect(() => {
if (!open) return;
const idx = options.findIndex((o) => o.value === value);
setActive(idx >= 0 ? idx : 0);
}, [open, options, value]);
useEffect(() => {
if (!open) return;
const onDown = (e: MouseEvent) => {
const t = e.target as Node;
if (!triggerRef.current?.contains(t) && !listRef.current?.contains(t)) setOpen(false);
};
document.addEventListener("mousedown", onDown);
return () => document.removeEventListener("mousedown", onDown);
}, [open]);
const choose = (opt: SelectOption) => {
if (opt.disabled) return;
onChange(opt.value);
setOpen(false);
triggerRef.current?.focus();
};
const onKeyDown = (e: ReactKeyboardEvent) => {
if (!open && (e.key === "Enter" || e.key === " " || e.key === "ArrowDown")) {
e.preventDefault();
setOpen(true);
return;
}
if (!open) return;
if (e.key === "ArrowDown") { e.preventDefault(); setActive((i) => Math.min(i + 1, options.length - 1)); }
else if (e.key === "ArrowUp") { e.preventDefault(); setActive((i) => Math.max(i - 1, 0)); }
else if (e.key === "Enter") { e.preventDefault(); choose(options[active]); }
else if (e.key === "Escape") { e.preventDefault(); setOpen(false); }
};
return (
<Field label={label} hint={hint} error={error} required={false} htmlFor={selectId} messageId={messageId}>
<button
ref={triggerRef}
id={selectId}
type="button"
role="combobox"
aria-expanded={open}
aria-haspopup="listbox"
aria-invalid={Boolean(error) || undefined}
aria-describedby={error || hint ? messageId : undefined}
disabled={disabled}
onClick={() => !disabled && setOpen((o) => !o)}
onKeyDown={onKeyDown}
className={cn(controlBase, controlClasses(error, disabled), "flex h-10 items-center justify-between gap-2 px-3 text-left")}
>
<span className={cn("truncate", selected ? "text-text" : "text-text-tertiary")}>
{selected ? selected.label : placeholder}
</span>
<ChevronDown size={16} className={cn("shrink-0 text-text-tertiary transition-transform", open && "rotate-180")} aria-hidden />
</button>
{open && position && mounted && createPortal(
<div
ref={listRef}
role="listbox"
className="z-50 overflow-auto rounded-lg border border-border bg-surface py-1 shadow-lg"
style={position.style}
>
{options.map((opt, i) => {
const on = opt.value === value;
return (
<div
key={opt.value}
role="option"
aria-selected={on}
aria-disabled={opt.disabled || undefined}
onMouseEnter={() => setActive(i)}
onMouseDown={(e) => e.preventDefault()}
onClick={() => choose(opt)}
className={cn(
"flex cursor-pointer items-center justify-between gap-2 px-3 py-1.5 text-sm text-text transition-colors",
opt.disabled ? "cursor-not-allowed opacity-40" : "hover:bg-bg-hover",
i === active && !opt.disabled && "bg-bg-secondary"
)}
>
<span className="truncate">{opt.label}</span>
{on && <Check size={14} className="shrink-0 text-accent" aria-hidden />}
</div>
);
})}
</div>,
document.body
)}
</Field>
);
}Dependencies
To use Select you also need the following. Copy these into your project alongside it.
Recommended folder structure
project structure
src/components/ui/ ├─ field.tsx └─ select.tsx src/hooks/ ├─ use-mounted.ts └─ use-popover-position.ts src/lib/ └─ utils.ts
Dependency files
These supporting files aren’t components — copy each one into the matching path above.
src/components/ui/field.tsx
field.tsx
"use client";
import { type ReactNode } from "react";
import { cn } from "@/lib/utils";
interface FieldCounter {
text: string;
warn?: boolean;
}
interface FieldProps {
label?: string;
hint?: string;
error?: string;
required?: boolean;
htmlFor?: string;
counter?: FieldCounter;
messageId?: string;
children: ReactNode;
}
export function Field({
label,
hint,
error,
required,
htmlFor,
counter,
messageId,
children,
}: FieldProps) {
const message = error || hint;
return (
<div className="flex w-full flex-col gap-1.5">
{label && (
<label
htmlFor={htmlFor}
className="flex items-center gap-1 text-[13px] font-medium text-text"
>
{label}
{required && (
<span className="text-error" aria-hidden>
*
</span>
)}
</label>
)}
{children}
<div className="flex items-start justify-between gap-3">
<p
id={messageId}
className={cn("text-xs leading-snug", error ? "text-error" : "text-text-secondary")}
>
{message || "\u00A0"}
</p>
{counter && (
<span
className={cn(
"shrink-0 text-xs tabular-nums",
counter.warn ? "text-error" : "text-text-tertiary"
)}
>
{counter.text}
</span>
)}
</div>
</div>
);
}
export const controlBase = cn(
"w-full rounded-lg border text-sm bg-surface text-text transition-colors",
"placeholder:text-text-tertiary",
"focus:outline-none focus-visible:outline-none focus-visible:border-accent",
"disabled:cursor-not-allowed disabled:bg-bg-secondary disabled:opacity-60",
"read-only:bg-bg-secondary"
);
export function controlClasses(error?: string, disabled?: boolean, readOnly?: boolean) {
return cn(
error ? "border-error focus-visible:border-error" : "border-border",
readOnly && "read-only:bg-bg-secondary",
disabled && "text-text-tertiary"
);
}src/hooks/use-mounted.ts
use-mounted.ts
"use client";
import { useState, useEffect } from "react";
/**
* Returns true once the component has mounted on the client.
* Useful for portals and anything that needs `document` to exist.
*/
export function useMounted(): boolean {
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
return mounted;
}src/hooks/use-popover-position.ts
use-popover-position.ts
"use client";
import { useState, useEffect, useCallback, type RefObject, type CSSProperties } from "react";
interface PopoverPositionOptions {
align?: "start" | "center" | "end";
gap?: number;
viewportPadding?: number;
preferredHeight?: number;
matchWidth?: boolean;
minWidth?: number;
}
interface PopoverPosition {
placement: "top" | "bottom";
style: CSSProperties;
}
/**
* Compute a fixed-position popover style anchored to a ref element.
* Opens downward by default; flips upward when there isn't room below
* AND there's more room above. Clamps horizontally so nothing renders
* past the viewport edge. Re-measures on scroll/resize while open.
*/
export function usePopoverPosition(
anchorRef: RefObject<HTMLElement | null>,
open: boolean,
options: PopoverPositionOptions = {}
): PopoverPosition | null {
const {
align = "start",
gap = 4,
viewportPadding = 8,
preferredHeight = 320,
matchWidth = false,
minWidth,
} = options;
const [position, setPosition] = useState<PopoverPosition | null>(null);
const measure = useCallback(() => {
const anchor = anchorRef.current;
if (!anchor) return;
const rect = anchor.getBoundingClientRect();
const vw = window.innerWidth;
const vh = window.innerHeight;
const spaceBelow = vh - rect.bottom - viewportPadding;
const spaceAbove = rect.top - viewportPadding;
const placement =
spaceBelow < Math.min(preferredHeight, 160) && spaceAbove > spaceBelow
? "top"
: "bottom";
const maxHeight = Math.max(
120,
Math.min(preferredHeight, placement === "top" ? spaceAbove : spaceBelow)
);
const width = matchWidth ? rect.width : minWidth;
let left = align === "end" && width ? rect.right - width : rect.left;
if (align === "center" && width)
left = rect.left + rect.width / 2 - width / 2;
left = width
? Math.min(Math.max(left, viewportPadding), vw - width - viewportPadding)
: Math.min(Math.max(left, viewportPadding), vw - viewportPadding);
setPosition({
placement,
style: {
position: "fixed",
top: placement === "top" ? undefined : rect.bottom + gap,
bottom: placement === "top" ? vh - rect.top + gap : undefined,
left,
width: matchWidth ? rect.width : undefined,
minWidth: !matchWidth ? minWidth : undefined,
maxHeight,
},
});
}, [anchorRef, align, gap, viewportPadding, preferredHeight, matchWidth, minWidth]);
useEffect(() => {
if (!open) {
setPosition(null);
return;
}
measure();
window.addEventListener("scroll", measure, true);
window.addEventListener("resize", measure);
return () => {
window.removeEventListener("scroll", measure, true);
window.removeEventListener("resize", measure);
};
}, [open, measure]);
return position;
}src/lib/utils.ts
utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
/**
* Merge class names with clsx semantics + Tailwind conflict resolution.
* Prefer this in all components.
*/
export function cn(...inputs: ClassValue[]): string {
return twMerge(clsx(inputs));
}
/**
* Concatenate class names, filtering out falsy values.
* @deprecated Prefer {@link cn} — it also resolves Tailwind class conflicts.
*/
export function cx(...args: (string | false | null | undefined)[]): string {
return args.filter(Boolean).join(" ");
}
/**
* Focus ring style helper.
* @deprecated Focus rings are now handled globally via the
* `:focus-visible` rule in `globals.css` and the `focus-visible:*`
* utilities. This remains only for backwards compatibility.
*/
export function ring(color: string = "var(--color-accent)") {
return { outlineColor: color };
}