Date Picker

A field that opens a Calendar. It is that composition and two things the composition always needs anyway: one place that owns the selection, because the field's text and the grid sit on opposite sides of a portal, and a rule for when picking a day closes the popup, which the calendar cannot decide because it does not know it is in one.

Import

import { DatePicker } from "@forte-ui/react";

Eight parts. The full anatomy, with every optional layer present:

<DatePicker.Root mode="single" selected={date} onSelect={setDate}>
  <DatePicker.Trigger aria-label="Due date">
    <DatePicker.Value placeholder="Pick a date" />
    <DatePicker.Icon />
  </DatePicker.Trigger>
  <DatePicker.Popup>
    <DatePicker.Calendar />
    <DatePicker.Footer>
      <DatePicker.Clear />
    </DatePicker.Footer>
  </DatePicker.Popup>
</DatePicker.Root>

Most pickers need less: the demo above is Root → Trigger → Popup and nothing else.

Selection

Root owns it, and takes the same three modes Calendar does — single, multiple, range — with selected typed to match. Pass selected with onSelect to control it; leave it off and the picker keeps its own state.

Controlled-ness is decided from whether selected was passed, not from whether it is currently defined, so the idiomatic useState<Date>() starting at undefined does not silently begin life uncontrolled.

When the popup closes

closeOnSelect follows the mode unless you say otherwise:

Picking several days

A multiple picker never closes on its own, so it needs a way out that is not the Escape key. DatePicker.Footer is the actions row for that, and because the surface really is a popover, a plain Popover.Close works inside it.

DatePicker.Clear empties the selection. It disables itself when there is nothing to clear and when Root is required — disabled rather than hidden, because a control that disappears as you reach for it is worse than one that is visibly unavailable, and the popup would reflow under the pointer.

Bounds and disabled days

DatePicker.Calendar forwards every Calendar prop it does not own itself, so minDate, maxDate, disabled, numberOfMonths, captionLayout, showWeekNumbers and the rest behave exactly as they do on a bare calendar. What it does own — and therefore does not forward — is mode, selected, onSelect, required and locale, all of which come from Root so the field and the grid cannot disagree.

In a form

The trigger is a <button>, so pair it with <Field.Label nativeLabel={false}>. A native <label> would hand the trigger its :hover state and open the calendar on every label click; with it off the two are wired together with aria-labelledby instead — which is also what gives the trigger its accessible name, so no aria-label is needed here.

That wiring is not automatic for a popover trigger the way it is for an Input or a Select.Trigger, which read the field context themselves. DatePicker.Trigger renders through Base UI's Field.Control to get it — so the label and the Field.Description both reach the button, and outside a Field.Root nothing changes.

The picker holds no form value of its own. Submit the date from your own state, or render a hidden input beside the trigger:

<input type="hidden" name="starts" value={date ? date.toISOString().slice(0, 10) : ""} />

Sizes and variants

Same two axes as every other control in the library: size for the field's height, padding and text; variant for how loud it is. outline reads as a form control, soft as a filled field, ghost as an inline affordance.

Formatting the field

The trigger shows a medium date in Root's locale. range renders as from – to with an en dash, and multiple collapses past two days into Aug 27, 2026 +3 — a field that grows as you pick would reflow the form around it, and the full list is in the popup either way.

formatValue replaces all of that:

<DatePicker.Root
  selected={date}
  onSelect={setDate}
  formatValue={(value) =>
    value ? new Intl.DateTimeFormat("en-GB", { dateStyle: "full" }).format(value) : null
  }
>

Return null to fall back to DatePicker.Value's placeholder.

Accessibility

The trigger must have an accessible name — a <Field.Label nativeLabel={false}> in the same <Field.Root>, or an aria-label. In development it warns once if it ends up with neither.

Everything else is the calendar's, which is documented on its own page: a real <table role="grid">, a roving tabindex, and days that are aria-disabled rather than disabled so navigation can cross them.

DatePicker.Calendar turns autoFocus on by default, the opposite of Calendar's own default. There is a press behind this calendar, so the first arrow key should move a day rather than do nothing; a calendar sitting in the page has no such press, which is why the base component leaves focus where it was.

The glyph is aria-hidden and takes no pointer events, so the field's own cursor shows through it. The value is the trigger's text, which means a screen reader announces the label and the chosen date together, with no extra wiring.

Theming

Every property below is declared on DatePicker.Trigger, so override them there — through its className or an inline style — not on an ancestor, where the part's own declaration would beat the inherited value.

The popup's surface is not restyled by this component. It is a Popover.Popup, keeps data-forte="popover-popup" and every --forte-popover-* knob, and the only thing the picker does to it is step the surface padding down — a calendar arrives with its own measures, and a full --forte-surface-p around them reads as a frame rather than a margin. The column inside it is this component's own part, data-forte="date-picker-panel", which is what you target to reach this popup rather than every popover on the page.

DatePicker.Clear is a Button and tags itself data-forte="button", the way every composed component in the library does — scope it as [data-forte="date-picker-footer"] [data-forte="button"].

API reference

DatePicker.Root

DatePicker.Trigger

DatePicker.Value

DatePicker.Icon

DatePicker.Popup

DatePicker.Calendar

DatePicker.Footer

DatePicker.Clear