Browse docs

DatePicker

DatePicker is a form-connected single-date field: a read-only text input paired with a Calendar popup. It integrates with DashForm, RBAC, and the Dashforge field layout automatically — registration, validation, error gating, reactive visibility, and access control are handled internally. The name prop connects the field to the form schema.

The stored value is a plain ISO calendar date — YYYY-MM-DD — or null. Unlike the native DateTimePicker, a pure date carries no time and no time zone, which removes the whole class of DST round-trip hazards.

DatePicker stores a date only. For date and time, use DateTimePicker. The calendar popup, grid keyboard model, and localization come from the headless @dashforge/calendar-core engine.

Quick Start

tsx

import { DashForm } from '@dashforge/forms';
import { DatePicker } from '@dashforge/ui';

<DashForm onSubmit={(data) => console.log(data)}>
  <DatePicker
    name="startDate"
    label="Start date"
    rules={{ required: 'Please pick a date' }}
  />
</DashForm>

Examples

A basic field — click the input or the calendar icon to open the popup.

Start date

<DatePicker name="startDate" label="Start date" />

Constrained dates

minDate / maxDate bound the selectable range; disabledDates and the isDateDisabled predicate block specific days.

Booking date

May 2026 only

<DatePicker
  name="bookingDate"
  label="Booking date"
  defaultValue="2026-05-15"
  minDate="2026-05-01"
  maxDate="2026-05-31"
  helperText="May 2026 only"
/>

Validation

Pass required and rules — the field reports errors through the form bridge, gated on touch / submit.

Deadline

Required field

<DatePicker
  name="deadline"
  label="Deadline"
  required
  rules={{ required: 'Please pick a deadline' }}
  helperText="Required field"
/>

Week start & locale

locale drives both the calendar names and the input's display format; weekStartDay sets the popup calendar's first column.

Date de début

<DatePicker
  name="dateDebut"
  label="Date de début"
  defaultValue="2026-05-20"
  locale="fr-FR"
  weekStartDay={1}
/>

API

Prop	Type	Default	Description
`name`	`string`	—	Field name — the bridge registration key. Required.
`label`	`ReactNode`	—	Field label.
`helperText`	`ReactNode`	—	Hint text below the control.
`rules`	`RegisterOptions`	—	Validation rules forwarded to the form bridge.
`required`	`boolean`	`false`	Adds the label asterisk.
`error`	`boolean`	—	Explicit error state (overrides the bridge's auto error).
`disabled`	`boolean`	`false`	Disables the field.
`placeholder`	`string`	—	Shown when no date is selected.
`layout`	`'stacked' \| 'inline' \| 'floating'`	`'stacked'`	Label / control layout. `floating` is downgraded to `stacked`.
`value`	`ISODate \| null`	—	Controlled value.
`defaultValue`	`ISODate \| null`	—	Uncontrolled initial value.
`onChange`	`(value: ISODate \| null) => void`	—	Fired with the new date.
`minDate` / `maxDate`	`ISODate`	—	Selectable range bounds (inclusive).
`disabledDates`	`ISODate[]`	—	Explicit list of disabled dates.
`isDateDisabled`	`(date: ISODate) => boolean`	—	Predicate disabling arbitrary dates.
`weekStartDay`	`WeekDay`	`0`	First-column weekday of the popup calendar.
`locale`	`string`	`'en-US'`	BCP-47 locale for the calendar + display format.
`visibleWhen`	`(engine: Engine) => boolean`	—	Reactive visibility predicate.
`access`	`AccessRequirement`	—	RBAC access requirement.
`fullWidth`	`boolean`	`false`	Stretches the field to its container width.
`testId`	`string`	—	Test id applied to the field root.

Notes

ISO YYYY-MM-DD storage. The bridge value is a plain calendar date or null — no time, no offset. Read it directly; no parsing needed.
Read-only input. The text input cannot be typed into — it is set only via the calendar popup, so the stored value is always a valid date.
layout="floating" is not supported (the end-adornment icon would collide with a floating label) — it falls back to stacked.
Native alternative. For date + time in one control, or to lean on the browser's native picker, see DateTimePicker.

Capabilities

Controlled

DatePicker works as a standard controlled component with ISO date storage.

tsx

<DatePicker
  value={startDate}
  onChange={(iso) => setStartDate(iso)}
  label="Start date"
/>

React Hook Form ready

Inside DashForm the field registers automatically — validation, error gating, and touch tracking flow through the bridge.

tsx

<DashForm>
  <DatePicker
    name="deadline"
    label="Deadline"
    rules={{ required: 'Please pick a deadline' }}
  />
</DashForm>

Reactive visibility

visibleWhen shows / hides the field from engine-driven form state.

tsx

<DatePicker
  name="scheduledDate"
  label="Scheduled date"
  visibleWhen={(engine) => engine.getNode('schedule')?.value === true}
/>

RBAC access control

The access prop maps an RBAC decision to one of three field states — no manual checks in the parent.

tsx

<DatePicker
  name="overrideDate"
  label="Override date"
  access={{ resource: 'invoice', action: 'update', onUnauthorized: 'disable' }}
/>

Field	Type	Description
`resource`	`string`	The resource being protected.
`action`	`string`	The action being checked.
`onUnauthorized`	`'hide' \| 'disable' \| 'readonly'`	What to render when the user lacks permission. Defaults to `'hide'`.