@sam-mu/react-date-range-picker

An accessible, zero-dependency React date & date-range picker: dual-month calendar, range presets, min/max & disabled dates, full keyboard navigation, localization via Intl, semantic color variants, and CSS-variable theming (light + opt-in dark).

No date library — all date math is done with native Date in a tiny, tree-shakeable engine. Peer-depends on React only; positioning uses Floating UI.

Install

npm install @sam-mu/react-date-range-picker react react-dom

Usage

import { DateRangePicker } from '@sam-mu/react-date-range-picker';
import '@sam-mu/react-date-range-picker/styles.css';

function Example() {
  const [range, setRange] = React.useState({ start: null, end: null });
  return <DateRangePicker label="Trip dates" value={range} onChange={setRange} />;
}

Single date

<DateRangePicker mode="single" value={date} onChange={setDate} />

Constraints, presets, locale

<DateRangePicker
  min={new Date()}                                  // no past dates
  max={addDays(new Date(), 90)}
  disabledDate={(d) => d.getDay() === 0}            // no Sundays
  numberOfMonths={2}
  weekStartsOn={1}                                  // Monday
  locale="en-GB"
  format={{ day: '2-digit', month: 'short', year: 'numeric' }}
/>

Time (hours / minutes / seconds, AM·PM or 24h)

// Range with 12-hour time + AM/PM
<DateRangePicker withTime hourCycle="h12" value={range} onChange={setRange} />

// Single timestamp with seconds, 24-hour
<DateRangePicker mode="single" withTime showSeconds hourCycle="h24" />

• withTime adds time controls in the popover (one per endpoint in range mode).
• hourCycle: 'h12' (default, shows AM/PM) or 'h24'.
• showSeconds adds a seconds field.
• Picked days keep/assign clock times (range defaults: start 00:00:00, end 23:59:59); the trigger display and value include time. With withTime, the popover stays open after a range completes so you can adjust the clock, then press Done.

Custom presets

<DateRangePicker
  presets={[
    { label: 'Next 7 days', range: (t) => ({ start: t, end: addDays(t, 6) }) },
    { label: 'This quarter', range: (t) => ({ start: startOfQuarter(t), end: endOfQuarter(t) }) },
  ]}
/>

Props (highlights)

| Prop | Type | Default | Notes | |---|---|---|---| | mode | 'range' \| 'single' | 'range' | | | value / defaultValue | {start,end} | Date | — | shape depends on mode | | onChange | (value, meta) => void | — | meta.type: start/complete/preset/clear | | min / max | Date | string | number | — | bounds | | disabledDate | (date) => boolean | — | per-day disable | | numberOfMonths | number | 2 (range) / 1 | months shown | | weekStartsOn | 0 \| 1 | 0 | Sun / Mon | | locale / format | string / Intl opts | system | localization | | showPresets / presets | boolean / array | range only | shortcuts | | clearable closeOnComplete | boolean | true | | | variant | primary|success|danger|warning|info|neutral | primary | accent color | | size / unstyled / classNames | — | — | styling | | open / defaultOpen / onOpenChange | — | — | controlled popover | | name | string | — | hidden ${name}_start / ${name}_end inputs |

Imperative ref: { open, close, toggle, clear, focus, getValue }.

Accessibility

• Trigger is a role="combobox" with aria-haspopup="dialog" / aria-expanded.
• Calendar is a role="grid"; days are gridcells with aria-selected, aria-disabled, full-date aria-label, and aria-current="date" for today.
• Roving-tabindex keyboard nav: ← → ↑ ↓ move by day/week, Home/End jump to week edges, PageUp/PageDown change month (Shift = year), Enter/Space select, Esc closes and returns focus to the trigger.
• Verified with jest-axe (closed + open) — zero violations.

Theming

Accent colors derive from a single --drp-accent via color-mix, so variant (or a custom color) is one variable:

.brand { --drp-accent: #7c3aed; }

Dark mode is opt-in: add data-theme="dark" (or class="dark") to any ancestor. Override surface tokens (--drp-bg, --drp-panel-bg, --drp-border, --drp-radius, …) to fully reskin. Set unstyled to drop all default CSS.

Scripts

npm run dev     # Vite playground
npm run build   # tsup -> dist (ESM + CJS + CSS)
npm test        # vitest (date engine + component + a11y)
npm run size    # size-limit budget

License

MIT © sam-mu