DatePicker

Overview

DatePicker is a controlled input that opens a calendar dropdown for selecting a single date or a date range. Key features:

• Single or range selection — controlled by isRange. Range mode uses a { from, to } value object.
• Single or dual calendar — mode="single" shows one month at a time; mode="dual" shows two months side-by-side for easier range picking.
• Shortcuts — pass a shortcuts array for quick-select options (e.g. "Today", "This week").
• Localization — driven by a BCP-47 locale code; any label can be overridden via localeText.
• Form-compatible events — onChange and onBlur mimic the React input event shape (e.target.name, e.target.value, e.target.type = 'date').

Import

import { DatePicker } from '@unflow.io/ui/components/DatePicker';

Props

Value types

The value and onChange event type depend on whether isRange is set:

Important: Always pass Date objects. Strings and timestamps (numbers) are rejected at runtime.

Single date

'use client';
import { useState } from 'react';
import { DatePicker } from '@unflow.io/ui/components/DatePicker';

export function Example() {
  const [value, setValue] = useState<Date | null>(null);

  return (
    <DatePicker
      name="date"
      label="Select a date"
      isRange={false}
      mode="single"
      value={value}
      onChange={(e) => setValue(e.target.value as Date | null)}
    />
  );
}

Date range

'use client';
import { useState } from 'react';
import { DatePicker } from '@unflow.io/ui/components/DatePicker';

type RangeValue = { from: Date | null; to: Date | null } | null;

export function Example() {
  const [value, setValue] = useState<RangeValue>(null);

  return (
    <DatePicker
      name="dateRange"
      label="Select a date range"
      isRange
      mode="dual"
      value={value}
      onChange={(e) => setValue(e.target.value as RangeValue)}
    />
  );
}

Range selection works in two steps: the first click sets from; the second click sets to. Clicking a date before the current from resets from and starts the selection over.

With shortcuts

const now = new Date();
const shortcuts = [
  { label: 'Today', value: { from: startOfDay(now), to: endOfDay(now) } },
  {
    label: 'This week',
    value: {
      from: startOfDay(new Date(now.getFullYear(), now.getMonth(), now.getDate() - now.getDay())),
      to: endOfDay(new Date(now.getFullYear(), now.getMonth(), now.getDate() - now.getDay() + 6)),
    },
  },
];

<DatePicker
  name="dateRange"
  label="Select a period"
  isRange
  mode="dual"
  value={value}
  shortcuts={shortcuts}
  onChange={(e) => setValue(e.target.value as RangeValue)}
/>

Each shortcut value must match the picker's mode: a plain Date when isRange={false}, or a { from, to } object when isRange={true}.

Localization

<DatePicker
  name="date"
  label="Selecionar data"
  isRange={false}
  mode="single"
  locale="pt"
  weekStartsOn={1}
  localeText={{ apply: 'Aplicar', cancel: 'Cancelar', reset: 'Limpar' }}
  value={value}
  onChange={(e) => setValue(e.target.value as Date | null)}
/>

Locale resolution priority (highest → lowest):

1. localeText prop — inline overrides for any label
2. i18n translations — registered translations for the resolved locale
3. Intl API fallback — automatic month/weekday names for unregistered locales

weekStartsOn accepts 0 (Sunday) through 6 (Saturday) and overrides the locale's CLDR default.

All overridable labels via localeText:

Events

Both onChange and onBlur receive a synthetic event that mirrors the React input event shape:

type DatePickerChangeEvent = {
  type: 'change';
  target: { name: string; value: DatePickerValue; type: 'date' };
  currentTarget: { name: string; value: DatePickerValue };
  nativeEvent?: Event;
  preventDefault: () => void;
  stopPropagation: () => void;
  persist: () => void;
};

This makes DatePicker compatible with form libraries like React Hook Form that read e.target.name and e.target.value.

Customization (slotProps)

Accessibility

• The calendar toggle button uses localeText.toggleOn / localeText.toggleOff as its aria-label — always provide translated values when customizing locale.
• Inside the calendar grid, arrow keys move focus between days; Enter and Space select the focused day.
• The month/year selectors are keyboard-accessible dropdowns.
• Provide an accessible label or aria-label on the component so screen readers can identify the input field.