Picker

Installation

Usage

Basic Usage

Click the input to toggle the popover panel. The open state and the input value each support controlled (open / value) and uncontrolled (defaultOpen / defaultValue) modes.

"use client";import { useState } from "react";import { ChevronDown } from "lucide-react";import { Picker } from "@/ui";export default function Demo() {  const [value, setValue] = useState("");  return (    <Picker      value={value}      onValueChange={setValue}      placeholder="Click to open"      trailing={<ChevronDown />}    >      <div className="w-64 p-3 text-sm text-muted-foreground">        Any content can be rendered inside the popover panel.      </div>    </Picker>  );}

DatePicker Assembly

Picker is a building block, not a finished widget. Compose it with Calendar to assemble a date picker directly in your page — or use the shipped DatePicker component, which is this exact assembly. Selecting a date updates the input value and closes the panel via onOpenChange.

"use client";import { useState } from "react";import { Calendar as CalendarIcon } from "lucide-react";import { Calendar, Picker } from "@/ui";export default function Demo() {  const [open, setOpen] = useState(false);  const [text, setText] = useState("");  const [visibleMonth, setVisibleMonth] = useState(() => Temporal.Now.plainDateISO());  const [selectedDate, setSelectedDate] = useState<Temporal.PlainDate | null>(null);  const handleTextChange = (text: string) => {    setText(text);    if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) return;    const date = Temporal.PlainDate.from(text);    setSelectedDate(date);    setVisibleMonth(date);  };  return (    <Picker      open={open}      onOpenChange={setOpen}      value={text}      onValueChange={handleTextChange}      placeholder="Select or type a date"      trailing={<CalendarIcon />}      onKeyDown={(e) => {        if (e.key === "Enter" && /^\d{4}-\d{2}-\d{2}$/.test(text)) {          e.preventDefault();          const date = Temporal.PlainDate.from(text);          setSelectedDate(date);          setVisibleMonth(date);          setOpen(false);        }      }}    >      <Calendar        visibleMonth={visibleMonth}        onVisibleMonthChange={setVisibleMonth}        value={selectedDate}        onChange={(date) => {          setSelectedDate(date);          setVisibleMonth(date);          setText(date.toString());          setOpen(false);        }}        firstDayOfWeek={1}      />    </Picker>  );}

The same assembly model applies to other pickers: combine Picker with any panel content (a list, a color grid, a tree) inside the children slot.

API Reference

High-level Components

Picker

Behavior notes:

• The popover is a native popover="manual" element positioned with CSS anchor positioning; the panel is anchored to the input, aligned to the bottom-start edge, with min-width: anchor-size(width) and a flip-block fallback.
• Clicking the input toggles the panel. Pressing Escape or pressing outside both the input and the panel closes it.
• Keyboard: ArrowDown opens the panel when it is closed, and Escape closes it — built in, no wiring needed.
• Consumer onKeyDown / onClick handlers are composed with the internal behavior, not overridden; the internal open and Escape-close are skipped when the consumer calls preventDefault.
• In controlled mode the parent must respond to onValueChange by updating value, otherwise typing in the input is blocked.
• The popover positioning depends on CSS anchor positioning support — make sure the target environment supports it.

Picker panels come in two keyboard flavors, wired with hooks — pick the one matching the panel content:

• Virtual focus (highlighted lists): use useCombobox. The input keeps focus while the panel is open; ArrowDown / ArrowUp move the highlight and Enter selects.
• Real focus (grids, forms, any panel of real focusable controls): use usePanelFocus with the panelRef prop. ArrowDown / ArrowUp move focus into the panel's first / last focusable element while the panel is open.

When the panel closes, focus returns to the input if it would otherwise be lost (e.g. Escape while the focus is inside the panel).

Composable Components

PickerRoot

Wrapper around the input; carries the anchor name consumed by the panel. Extends all native div props.

PickerInput

The trigger input. Extends all native input props (except className).

PickerContent

The popover panel. A native popover="manual" element; call showPopover() / hidePopover() imperatively, and position it manually via style={{ positionAnchor: ... }} (the anchor name set on the corresponding PickerRoot); it has no positionAnchor prop.