DatePicker

DatePicker is a form-connected single-date field: a read-only trigger button paired with a Calendar popover. It integrates with DashForm and RBAC 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.

Quick Start

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

<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 trigger to open the calendar popover.

import { DatePicker } from '@dashforge/tw';

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

Constrained dates

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

import { DatePicker } from '@dashforge/tw';

<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.

import { DatePicker } from '@dashforge/tw';

<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 trigger's display format; weekStartDay sets the popover calendar's first column.

import { DatePicker } from '@dashforge/tw';

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

Theme defaults

Configure <DatePicker> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    DatePicker: {
      defaults: { layout: 'stacked', weekStartDay: 1, locale: 'en-GB', fullWidth: false },
    },
  },
});

Configurable axes (DatePickerVariantProps):

Non-visual axes (name, rules, label, helperText, placeholder, required, error, disabled, value, defaultValue, onChange, minDate, maxDate, disabledDates, isDateDisabled, access, visibleWhen) are per-instance — data / behavior / bridge integration — not theme-configurable.

Precedence chain (lowest → highest):

1. Built-in defaults (layout: 'stacked', weekStartDay: 0, locale: 'en-US', fullWidth: false).
2. theme.components.DatePicker.defaults (application-wide).
3. Instance prop (<DatePicker weekStartDay={1} fullWidth />) — wins over theme.
4. sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.DatePicker.defaults autocompletes to the four axes above.

Reactivity: useComponentDefaults('DatePicker') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Slots & slotProps

<DatePicker> is a compound component with 6 named slots. Each slot accepts a { className?: string } override via slotProps:

<DatePicker
  name="startDate"
  label="Start date"
  sx="max-w-xs"
  slotProps={{ trigger: { className: 'rounded-lg' } }}
/>

Use sx for a root-level class override; use slotProps for a specific inner region (e.g. trigger border color, errorText weight). The popover calendar itself is themable via theme.components.Calendar.defaults — see Calendar.

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 trigger. The trigger cannot be typed into — the value is set only via the calendar popover, so the stored date is always valid.
• 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.

<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.

<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.

<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.

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