InputsReact

Date Picker

A DateField with a calendar popup: the field is the primary input, a trigger button opens a dialog that holds a Calendar, and both edit one value, an ISO 8601 string such as '2026-11-12'.

Compare in five frameworks

Rendered by React 19.3.1

Loading React…

import { Calendar } from '@hamur/react/calendar'
import { DatePicker } from '@hamur/react/date-picker'
import { Field } from '@hamur/react/field'

export default function DatePickerExample() {
  return (
    <Field.Root className="field">
      <Field.Label>Due date</Field.Label>
      <DatePicker.Root locale="en-US" today="2026-11-07">
        <DatePicker.Control className="date-field date-picker-control">
          <DatePicker.Input className="date-field-input">
            {({ segments }) =>
              segments.map((segment) => (
                <DatePicker.Segment
                  key={segment.index}
                  segment={segment}
                  className="date-field-segment"
                />
              ))
            }
          </DatePicker.Input>
          <DatePicker.Clear className="date-field-clear">
            ×
          </DatePicker.Clear>
          <DatePicker.Trigger className="date-picker-trigger">
            <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
              <path d="M2.5 3.5h11v10h-11zM2.5 6.5h11M5.5 1.5v3M10.5 1.5v3" />
            </svg>
          </DatePicker.Trigger>
        </DatePicker.Control>
        <DatePicker.Portal>
          <DatePicker.Positioner sideOffset={8}>
            <DatePicker.Popup className="popover date-picker-popup">
              <DatePicker.Calendar className="calendar">
                <div className="calendar-header">
                  <Calendar.PrevButton className="calendar-nav">‹</Calendar.PrevButton>
                  <Calendar.Heading className="calendar-heading" />
                  <Calendar.NextButton className="calendar-nav">›</Calendar.NextButton>
                </div>
                <Calendar.Grid className="calendar-grid">
                  {(grid) => (
                    <>
                      <Calendar.GridHeader>
                        <Calendar.GridRow>
                          {grid.weekdays.map((weekday) => (
                            <Calendar.HeaderCell
                              key={weekday.index}
                              weekday={weekday.index}
                              className="calendar-weekday"
                            />
                          ))}
                        </Calendar.GridRow>
                      </Calendar.GridHeader>
                      <Calendar.GridBody>
                        {grid.weeks.map((week, index) => (
                          <Calendar.GridRow key={index}>
                            {week.map((day) => (
                              <Calendar.Cell
                                key={day.date}
                                date={day.date}
                                className="calendar-cell"
                              >
                                <Calendar.Day className="calendar-day" />
                              </Calendar.Cell>
                            ))}
                          </Calendar.GridRow>
                        ))}
                      </Calendar.GridBody>
                    </>
                  )}
                </Calendar.Grid>
              </DatePicker.Calendar>
              <DatePicker.Close className="button date-picker-close">
                Close
              </DatePicker.Close>
            </DatePicker.Popup>
          </DatePicker.Positioner>
        </DatePicker.Portal>
      </DatePicker.Root>
    </Field.Root>
  )
}

Not measured yetTests passing in React

Not measured yetSize

Not measured yetMemory

Not measured yetSpeed

[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<DatePicker.Root>
  <DatePicker.Control>
    <DatePicker.Input>
      <DatePicker.Segment />
    </DatePicker.Input>
    <DatePicker.Clear />
    <DatePicker.Trigger />
  </DatePicker.Control>
  <DatePicker.Portal>
    <DatePicker.Positioner>
      <DatePicker.Popup>
        <DatePicker.Calendar />
        <DatePicker.Close />
      </DatePicker.Popup>
    </DatePicker.Positioner>
  </DatePicker.Portal>
</DatePicker.Root>

// Not in this example: DatePicker.Preset

Examples

Limits

min and max with isDateUnavailable for weekends, in a Field: the calendar disables them and a typed one is invalid.

DatePickerLimits.tsx

import { Calendar } from '@hamur/react/calendar'
import { DatePicker } from '@hamur/react/date-picker'
import { Field } from '@hamur/react/field'

// Saturday and Sunday are booked: the calendar disables them and a typed one is invalid.
const isWeekend = (date: string) => {
  const day = new Date(`${date}T00:00:00Z`).getUTCDay()
  return day === 0 || day === 6
}

export default function DatePickerLimitsExample() {
  return (
    <Field.Root className="field" validationMode="onChange">
      <Field.Label>Appointment</Field.Label>
      <DatePicker.Root
        locale="en-US"
        today="2026-11-07"
        min="2026-11-03"
        max="2026-12-18"
        isDateUnavailable={isWeekend}
      >
        <DatePicker.Control className="date-field date-picker-control">
          <DatePicker.Input className="date-field-input" />
          <DatePicker.Trigger className="date-picker-trigger">
            <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
              <path d="M2.5 3.5h11v10h-11zM2.5 6.5h11M5.5 1.5v3M10.5 1.5v3" />
            </svg>
          </DatePicker.Trigger>
        </DatePicker.Control>
        <DatePicker.Portal>
          <DatePicker.Positioner sideOffset={8}>
            <DatePicker.Popup className="popover date-picker-popup">
              <DatePicker.Calendar className="calendar">
                <div className="calendar-header">
                  <Calendar.PrevButton className="calendar-nav">‹</Calendar.PrevButton>
                  <Calendar.Heading className="calendar-heading" />
                  <Calendar.NextButton className="calendar-nav">›</Calendar.NextButton>
                </div>
                <Calendar.Grid className="calendar-grid">
                  {(grid) => (
                    <>
                      <Calendar.GridHeader>
                        <Calendar.GridRow>
                          {grid.weekdays.map((weekday) => (
                            <Calendar.HeaderCell
                              key={weekday.index}
                              weekday={weekday.index}
                              className="calendar-weekday"
                            />
                          ))}
                        </Calendar.GridRow>
                      </Calendar.GridHeader>
                      <Calendar.GridBody>
                        {grid.weeks.map((week, index) => (
                          <Calendar.GridRow key={index}>
                            {week.map((day) => (
                              <Calendar.Cell
                                key={day.date}
                                date={day.date}
                                className="calendar-cell"
                              >
                                <Calendar.Day className="calendar-day" />
                              </Calendar.Cell>
                            ))}
                          </Calendar.GridRow>
                        ))}
                      </Calendar.GridBody>
                    </>
                  )}
                </Calendar.Grid>
              </DatePicker.Calendar>
            </DatePicker.Popup>
          </DatePicker.Positioner>
        </DatePicker.Portal>
      </DatePicker.Root>
      <Field.Description className="muted">
        Weekdays from November 3 to December 18, 2026. Weekends are booked.
      </Field.Description>
      <Field.Error className="error" match="rangeUnderflow">
        The first free day is November 3.
      </Field.Error>
      <Field.Error className="error" match="rangeOverflow">
        The last free day is December 18.
      </Field.Error>
    </Field.Root>
  )
}

Form

Inside Field and Form with required and a name: the date submits as due=2026-11-12.

DatePickerForm.tsx

import * as React from 'react'
import { Calendar } from '@hamur/react/calendar'
import { DatePicker } from '@hamur/react/date-picker'
import { Field } from '@hamur/react/field'
import { Form } from '@hamur/react/form'

export default function DatePickerFormExample() {
  const [submitted, setSubmitted] = React.useState('')
  return (
    <Form
      className="stack"
      onFormSubmit={(_values, details) => {
        const form = details.event.target as HTMLFormElement
        setSubmitted([...new FormData(form)].map(([key, value]) => `${key}=${value}`).join('&'))
      }}
    >
      <Field.Root name="due" className="field">
        <Field.Label>Due date</Field.Label>
        <DatePicker.Root locale="en-US" today="2026-11-07" required>
          <DatePicker.Control className="date-field date-picker-control">
            <DatePicker.Input className="date-field-input" />
            <DatePicker.Trigger className="date-picker-trigger">
              <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
                <path d="M2.5 3.5h11v10h-11zM2.5 6.5h11M5.5 1.5v3M10.5 1.5v3" />
              </svg>
            </DatePicker.Trigger>
          </DatePicker.Control>
          <DatePicker.Portal>
            <DatePicker.Positioner sideOffset={8}>
              <DatePicker.Popup className="popover date-picker-popup">
                <DatePicker.Calendar className="calendar">
                  <div className="calendar-header">
                    <Calendar.PrevButton className="calendar-nav">‹</Calendar.PrevButton>
                    <Calendar.Heading className="calendar-heading" />
                    <Calendar.NextButton className="calendar-nav">›</Calendar.NextButton>
                  </div>
                  <Calendar.Grid className="calendar-grid">
                    {(grid) => (
                      <>
                        <Calendar.GridHeader>
                          <Calendar.GridRow>
                            {grid.weekdays.map((weekday) => (
                              <Calendar.HeaderCell
                                key={weekday.index}
                                weekday={weekday.index}
                                className="calendar-weekday"
                              />
                            ))}
                          </Calendar.GridRow>
                        </Calendar.GridHeader>
                        <Calendar.GridBody>
                          {grid.weeks.map((week, index) => (
                            <Calendar.GridRow key={index}>
                              {week.map((day) => (
                                <Calendar.Cell
                                  key={day.date}
                                  date={day.date}
                                  className="calendar-cell"
                                >
                                  <Calendar.Day className="calendar-day" />
                                </Calendar.Cell>
                              ))}
                            </Calendar.GridRow>
                          ))}
                        </Calendar.GridBody>
                      </>
                    )}
                  </Calendar.Grid>
                </DatePicker.Calendar>
              </DatePicker.Popup>
            </DatePicker.Positioner>
          </DatePicker.Portal>
        </DatePicker.Root>
        <Field.Error className="error" />
      </Field.Root>
      <button className="button" type="submit">
        Save
      </button>
      {submitted ? <pre className="output">{submitted}</pre> : null}
    </Form>
  )
}

API reference

61 props across 12 parts, in React syntax. className, style, render are listed once, under Shared props.

Calendar`DatePicker.Calendar`

The calendar of the popup: Calendar.Root (or RangeCalendar.Root) wired to the picker's value, limits, locale and visible month. Compose it with the Calendar parts (Calendar.PrevButton, Calendar.Heading, Calendar.Grid and the rest). It takes no part in the Field: the control already submits and validates the value. Renders a <div>.

Clear`DatePicker.Clear`

Clears the whole value, including a partly typed one. It is out of the tab order: Backspace clears a segment from the keyboard. Renders a <button>.

Close`DatePicker.Close`

A button that closes the popover. Renders a <button>.

Close props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

Control`DatePicker.Control`

The group that holds the field and the trigger, and the element the popup is anchored to. It is the field's root: it is named by the Field label, shows the Field's validity, and counts the popup as inside it, so moving focus into the calendar neither touches nor validates the field. Renders a <div>.

Input`DatePicker.Input`

The visual control: it wraps the segments. Its children are a function of the segments, since their order depends on the locale; without children it renders every segment. Renders a <div>.

Input props
Prop	Type	Default
`children`The segments, or a function of them: `({ segments }) => ...`.	`React.ReactNode \| ((context: { segments: FieldSegment[]; }) => React.ReactNode)`	`—`

Popup`DatePicker.Popup`

The dialog that holds the calendar and the presets. It is named "Choose date" unless you name it. Focus moves to the highlighted day when it opens, and returns to the trigger (or to the segment Alt+Down was pressed on) when it closes. Renders a <div>.

Popup props
Prop	Type	Default
`initialFocus`Determines the element to focus when the popover is opened.	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`	`—`
`finalFocus`Determines the element to focus when the popover is closed.	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`	`—`

Portal`DatePicker.Portal`

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div>.

Portal props
Prop	Type	Default
`keepMounted`Whether to keep the portal mounted in the DOM while the popup is hidden.	`boolean`	`false`
`container`A parent element to render the portal element into.	`HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`	`—`

Positioner`DatePicker.Positioner`

Positions the popup against the control (the field and the trigger together). Renders a <div>.

Positioner props
Prop	Type	Default
`align`How to align the popup relative to the specified side.	`Align`	`'start'`
`anchor`An element to position the popup against.	`Element \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null`	`—`
`positionMethod`Determines which CSS `position` property to use.	`"absolute" \| "fixed"`	`'absolute'`
`side`Which side of the anchor element to align the popup against.	`Side`	`'bottom'`
`sideOffset`Distance between the anchor and the popup in pixels.	`number \| OffsetFunction`	`0`
`alignOffset`Additional offset along the alignment axis in pixels.	`number \| OffsetFunction`	`0`
`collisionBoundary`An element or a rectangle that delimits the area that the popup is confined to.	`Boundary`	`'clipping-ancestors'`
`collisionPadding`Additional space to maintain from the edge of the collision boundary.	`Padding`	`5`
`sticky`Whether to maintain the popup in the viewport after	`boolean`	`false`
`arrowPadding`Minimum distance to maintain between the arrow and the edges of the popup.	`number`	`5`
`disableAnchorTracking`Whether to disable the popup from tracking any layout shift of its positioning anchor.	`boolean`	`false`
`collisionAvoidance`Determines how to handle collisions when positioning the popup.	`CollisionAvoidance`	`—`

Preset`DatePicker.Preset`

A button that sets the value to a date or a range, such as "Last 7 days". The value can be a function of today, which the picker reads from the clock after mount (or from today). It closes the popup like a day does. Renders a <button>.

Preset props
Prop	Type	Default
`value`requiredThe value the preset sets: a date (`'2026-11-07'`), a range (`{ start, end }`), or a function	`${number}-${number}-${number}` \| DateRange \| ((today: `${number}-${number}-${number}`) => `${number}-${number}-${number}` \| DateRange)	`—`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

Root`DatePicker.Root`

Groups all parts of a field with a calendar popup that picks one date. It renders no element. Values are ISO 8601 strings such as '2026-11-07'; onValueChange is called only with a complete, real date, or null.

Root props
Prop	Type	Default
`value`The date, `null` for none.	`${number}-${number}-${number}` \| null	`—`
`defaultValue`The date when initially rendered.	`${number}-${number}-${number}` \| null	`—`
`onValueChange`Event handler called when the date changes: a complete, real date, or `null`.	((value: `${number}-${number}-${number}` \| null, eventDetails: DatePickerRootChangeEventDetails) => void)	`—`
`autoComplete'bday'` gives the segments the `bday-day`, `bday-month` and `bday-year` autocomplete tokens.	`"off" \| "bday"`	`'off'`
`open`Whether the popup is open.	`boolean`	`—`
`defaultOpen`Whether the popup is initially open.	`boolean`	`false`
`onOpenChange`Event handler called when the popup opens or closes.	`((open: boolean, eventDetails: DatePickerRootOpenChangeEventDetails) => void)`	`—`
`onOpenChangeComplete`Event handler called after any animations complete when the popup opens or closes.	`((open: boolean) => void)`	`—`
`actionsRef`A ref to imperative actions: `unmount` and `close`.	`React.RefObject<PopoverRootActions \| null>`	`—`
`modal`Whether the rest of the page is inert while the popup is open.	`boolean \| "trap-focus"`	`false`
`closeOnSelect`Whether choosing a day (the second end of a range) or a preset closes the popup.	`boolean`	`true`
`min`The earliest date that can be chosen.	`${number}-${number}-${number}`	`—`
`max`The latest date that can be chosen.	`${number}-${number}-${number}`	`—`
`isDateUnavailable`Whether a date cannot be chosen but can hold focus.	((date: `${number}-${number}-${number}`, anchor: `${number}-${number}-${number}` \| null) => boolean)	`—`
`isDateDisabled`Whether a date is skipped by navigation and cannot be chosen.	((date: `${number}-${number}-${number}`) => boolean)	`—`
`locale`The BCP 47 locale of the field and the calendar.	`string`	`'en-US'`
`firstDayOfWeek`The first day of the week, 0 (Sunday) to 6.	`number`	`—`
`visibleMonth`The first visible month.	`${number}-${number}-${number}` \| `${number}-${number}` \| null	`—`
`onVisibleMonthChange`Event handler called when the visible month changes.	((month: `${number}-${number}`, eventDetails: DatePickerVisibleMonthChangeEventDetails) => void)	`—`
`visibleMonths`How many months are visible.	`number`	`1`
`pageBehavior`Whether Previous and Next move by the visible months or by one.	`"visible" \| "single"`	`'visible'`
`fixedWeeks`Whether every month shows six weeks.	`boolean`	`false`
`today`The date of today, for the calendar and the presets.	`${number}-${number}-${number}`	`—`
`timeZone`The time zone that decides what today is, when `today` is not given.	`string`	`—`
`labels`The texts the picker, the field and the calendar add (the trigger and popup names, the Close	`Partial<DatePickerLabels & DateFieldLabels & CalendarLabels>`	`—`
`forceLeadingZeros`Whether the day, month and hour show a leading zero.	`boolean`	`—`
`placeholderValue`The value an empty segment takes on its first Up or Down press.	`string`	`—`
`autoAdvance`Whether focus moves to the next segment when the typed number cannot get another digit.	`boolean`	`true`
`segmentRole`The role of the segments.	`DateFieldSegmentRole`	`'spinbutton'`
`onIncompleteChange`Event handler called when the segments change while no complete value exists.	`((parts: FieldParts, eventDetails: any) => void)`	`—`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`readOnly`Whether the user should be unable to change the value.	`boolean`	`false`
`required`Whether the user must fill in the field before submitting a form.	`boolean`	`false`
`invalid`Whether the field is invalid.	`boolean`	`false`
`name`Identifies the field when a form is submitted.	`string`	`—`
`form`Identifies the form that owns the hidden inputs.	`string`	`—`
`inputRef`A ref to access the first segment.	`React.Ref<HTMLInputElement>`	`—`
`children`	`React.ReactNode`	`—`

Segment`DatePicker.Segment`

One segment of the value. An editable segment (year, month, day, hour, minute, second, millisecond, day period) is a real <input> with the spinbutton role; a literal (/, :) is a <span> hidden from assistive technology., or a <span> for a literal. Renders an <input>.

Segment props
Prop	Type	Default
`segment`requiredThe segment to render, one of the `segments` the `Input` gives its children.	`FieldSegment`	`—`

Trigger`DatePicker.Trigger`

A button that opens the popup. It is named "Choose date", or "Change date, Saturday, November 7, 2026" once a date is chosen. It sits inside the control. Renders a <button>.

Trigger props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`
`id`ID of the trigger.	`string`	`—`

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`EnterSpace`	On the trigger: opens the popup and moves focus to the highlighted day	Trigger
`AltArrowDown`	On a segment: opens the popup and moves focus to the highlighted day	Segment
`ArrowDown`	On a segment: steps the segment as in DateField; it does not open the popup	Segment
`EnterSpace`	On a day: chooses it, closes the popup (with `closeOnSelect`) and returns focus	Popup
`Escape`	Closes the popup and returns focus to the trigger, or to the segment Alt+ArrowDown was used on	Popup
`AltArrowUp`	Inside the popup: closes it	Popup
`Tab`	Non-modal: from the last element of the popup closes it and continues after the trigger	Popup

Accessibility

What the parts set
Part	Sets	So that
Control	`role="group"`, named by the Field label (or `aria-label`); the Field's validity, `data-popup-open`	the group is announced once, "Birthday, group", and the error is on the segments
Trigger	`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`; `aria-label` "Choose date" or "Change date, Saturday, November 7, 2026"	the button says what it does and what the date is now
Trigger	`aria-disabled` while `readOnly`	a read only picker does not open, and says so
Popup	`role="dialog"` named "Choose date" (or your `aria-label`); `aria-modal` only with `modal`	a screen reader announces the dialog on open; the page is not hidden unless it is inert
Close	a button, "Close"	a touch screen reader can leave a popup it cannot Escape

Focus order

Each segment is a tab stop, then Clear is out of the order, then the Trigger. Nothing takes focus on mount.
Opening moves focus into the popup, to the calendar day; presets and the Close button come in DOM order around it.
Closing returns focus to the trigger, or to the segment the popup was opened from.
Tab from the last tabbable element of a non-modal popup closes it and moves to the next element after the trigger.

Installation

Anatomy

Examples

Limits

Form

API reference

CalendarDatePicker.Calendar

ClearDatePicker.Clear

CloseDatePicker.Close

ControlDatePicker.Control

InputDatePicker.Input

PopupDatePicker.Popup

PortalDatePicker.Portal

PositionerDatePicker.Positioner

PresetDatePicker.Preset

RootDatePicker.Root

SegmentDatePicker.Segment

TriggerDatePicker.Trigger