react-native-advanced-date-picker

A zero-dependency, fully customizable calendar date picker for React Native. Supports single, range, and multi-select date selection, week/month/year/time/datetime views, preset chips, per-day event badges, accessibility, optional web support, non-Gregorian calendars (Hijri, Persian, Buddhist), and both a simple prop-driven API and a fully headless useDatePicker() hook.

Features

Zero mandatory dependencies — date math uses native Intl API
Single, Range & Multi-select — pick one date, a date range, or any number of independent dates
Week / Month / Year / Time / DateTime views — granularity-aware grids, all powered by the same selection union
Pluggable calendar engines — Gregorian (default), Hijri (Umm al-Qura), Persian (Jalali / Borkowski), Buddhist Era — algorithmic, no third-party calendar libs
Preset chips — built-in Today / Last 7 days / This month / Last month + custom presets
Disabled date ranges & range-length constraints — booking-calendar friendly (disabledRanges, minRangeLength, maxRangeLength)
Per-date event badges — up to 3 colored dots per day with +N overflow, fully overrideable via renderBadge
Workday counter — countWorkdays(start, end, { holidays, weekendDays }) ships in the public API
Accessibility — accessibilityLabel / accessibilityState / accessibilityRole on every cell, modal announce-on-open, keyboard navigation hook (useKeyboardNav)
Headless mode — useDatePicker() exposes the full state machine (selection, dayProps(date), handlers) so you can build a 100% custom UI without giving up the engine
Web support — optional react-native-web peer + *.web.tsx shadow files (CSS transitions, <div role="dialog"> portal, ESC handler)
i18n ready — built-in English, Turkish, Arabic, Persian, Thai locales, add your own
Fully themeable — colors, granular fontSize / spacing / radius tokens, border radius, everything
Slot-based rendering — override individual layout pieces (renderMonthHeader, renderSaveButton, renderCloseIcon, renderWeekDayHeader, renderHolidayLabel, renderBadge) without rewriting the whole picker
Per-day callbacks — getDayColor, getDayStyle, getDayTextStyle, getDayContent, getBadge let you tweak individual cells based on runtime state
Uniform range-fill animation — every in-range cell fades in at the same time (160 ms cubic ease-out, native driver); disableAnimation turns it off
Safe-area aware modal — respects notch/status bar via react-native-safe-area-context when installed, platform-default fallback otherwise
Holidays support — highlight public holidays with labels, per-holiday color / icon / importance
Modal & Inline — use as a full-screen modal or embed inline
Style escape hatches on every surface (container, header, save/close buttons, day cells)
Composable — use the main component or import individual parts (CalendarList, DayCell, MonthGrid, YearGrid, WeekGrid, TimePicker, DateTimePicker, PresetBar)
TypeScript — full type definitions, including the Selection discriminated union and CalendarEngine interface

What's new in v0.3.0

v0.3.0 is an additive expansion — zero breaking changes. Every prop, callback shape, and import path from v0.2.x continues to work as-is.

New selection modes

// Multi-select — toggle any number of dates
<AdvancedDatePicker
  mode="multi"
  selectedDates={dates}
  onChange={(sel) => sel.kind === 'multi' && /* sel.dates is a Set<string> */}
/>

// Booking-calendar style range with blocked nights
<AdvancedDatePicker
  mode="range"
  disabledRanges={[{ start, end }, ...]}
  minRangeLength={2}
  maxRangeLength={14}
/>

Preset chips

import { AdvancedDatePicker, builtInPresets } from 'react-native-advanced-date-picker'

<AdvancedDatePicker
  mode="range"
  presets={[...builtInPresets, { id: 'next-7', label: 'Next 7 days', range: () => /* {start,end} */ }]}
/>

Per-date badges

<AdvancedDatePicker
  getBadge={({ day }) =>
    day.day === 12
      ? [{ color: '#10B981', label: 'Birthday' }, { color: '#F59E0B', label: 'Reminder' }]
      : []
  }
/>

Pluggable calendar engines

import { AdvancedDatePicker, hijri, ar } from 'react-native-advanced-date-picker'

// (string locales work too once the engine is wired through your own picker —
//  the built-in <AdvancedDatePicker> currently consumes engine via useDatePicker)
const picker = useDatePicker({ engine: hijri, locale: ar })

Headless hook

import { useDatePicker } from 'react-native-advanced-date-picker'

const picker = useDatePicker({ selectionMode: 'single' })
// picker.selection            — discriminated union { kind, ... }
// picker.calendarData         — MonthData[] (engine-aware)
// picker.dayProps(date)       — { onPress, isSelected, isInRange, isDisabled, ... }
// picker.handlers.selectDate / clear / setSelection

Workday counter

import { countWorkdays } from 'react-native-advanced-date-picker'

countWorkdays(start, end, { holidays, weekendDays: [0, 6] }) // → number

Accessibility & keyboard

Day cells expose accessibilityRole="button", dynamic accessibilityLabel (locale-aware: weekday, date, holiday, selected, today, unavailable), accessibilityState
<DatePickerModal> announces on open via AccessibilityInfo.announceForAccessibility
useKeyboardNav() hook drives Arrow / PageUp / PageDown / Home / End / Enter / Escape focus on the web

Web support

react-native-web is now an optional peer dependency. The package ships DatePickerModal.web.tsx and DayCell.web.tsx — Metro / webpack platform resolution picks them automatically; the native bundle is unaffected.

Migration

Nothing to migrate — your v0.2.x code keeps working. To opt into v0.3.0 features, just start passing the new props (presets, disabledRanges, getBadge, onChange) or import the new exports (useDatePicker, useKeyboardNav, builtInPresets, countWorkdays, hijri / persian / buddhist, ar / fa / th).

Installation

npm install react-native-advanced-date-picker
# or
yarn add react-native-advanced-date-picker

Optional peer dependency

For modal safe-area support (notch/status bar awareness), install:

yarn add react-native-safe-area-context

If not installed, the modal falls back to platform-default insets.

Quick Start

import { useState } from 'react'
import { AdvancedDatePicker } from 'react-native-advanced-date-picker'

const App = () => {
  const [visible, setVisible] = useState(false)
  const [startDate, setStartDate] = useState<Date | null>(null)
  const [endDate, setEndDate] = useState<Date | null>(null)

  return (
    <>
      <Button title="Pick dates" onPress={() => setVisible(true)} />
      <AdvancedDatePicker
        mode="range"
        locale="en"
        visible={visible}
        startDate={startDate}
        endDate={endDate}
        onDateChange={({ startDate, endDate }) => {
          setStartDate(startDate)
          setEndDate(endDate)
        }}
        onClose={() => setVisible(false)}
        minDate={new Date()}
      />
    </>
  )
}

Props

Core props

Prop	Type	Default	Description
`mode`	`'single' \| 'range'`	`'single'`	Date selection mode
`locale`	`string \| Locale`	`'en'`	Locale code or custom locale object
`startDate`	`Date \| null`	`null`	Selected start date
`endDate`	`Date \| null`	`null`	Selected end date (range mode)
`onDateChange`	`(payload) => void`	required	Called on date selection
`minDate`	`Date`	—	Minimum selectable date
`maxDate`	`Date`	—	Maximum selectable date
`theme`	`Partial<Theme>`	default	Theme overrides
`holidays`	`Holiday[]`	`[]`	Holidays to highlight
`showHolidays`	`boolean`	`true`	Show holiday labels
`disabledDates`	`(string \| Date)[]`	`[]`	Non-selectable dates
`months`	`number`	`12`	Number of months to render
`modal`	`boolean`	`true`	Modal or inline mode
`visible`	`boolean`	`false`	Modal visibility
`onClose`	`() => void`	—	Modal close callback
`onSave`	`() => void`	—	Save button callback
`showSaveButton`	`boolean`	`true`	Show save button in modal
`renderDay`	`(day, state) => ReactNode`	—	Custom day cell renderer (full override)

v0.2.0 — new props

Prop	Type	Default	Description
`disableAnimation`	`boolean`	`false`	Disable the range band fill animation. When `true`, the band appears instantly at full opacity.

Style escape hatches

Each accepts a standard StyleProp<ViewStyle> or StyleProp<TextStyle>. Styles are composed on top of defaults — you only override what you set.

Prop	Target
`style`	Root view style (inline mode, i.e. `modal={false}`)
`modalContainerStyle`	Slide-up sheet container in modal mode
`headerStyle`	Modal header row (contains the close icon)
`saveButtonStyle`	Save button wrapper
`saveButtonTextStyle`	Save button text
`closeButtonStyle`	Close (X) button wrapper
`closeButtonTextStyle`	Close (X) glyph text

Slot render props

Each is optional; when provided it replaces the default rendering for that slot only. All other slots keep their defaults.

Prop	Signature
`renderMonthHeader`	`({ month, year, theme, locale }) => ReactNode`
`renderWeekDayHeader`	`({ days, theme, locale }) => ReactNode`
`renderHolidayLabel`	`({ holiday, day, theme }) => ReactNode`
`renderSaveButton`	`({ onPress, theme, locale }) => ReactNode`
`renderCloseIcon`	`({ onPress, theme }) => ReactNode`

Per-day callbacks

Called for every non-empty day cell with runtime state (isSelected, isInRange, isDisabled, isToday, isHoliday, isSunday, isSaturday). Returning undefined falls through to the default rendering.

Prop	Signature	Effect
`getDayColor`	`({ day, state, theme }) => string \| undefined`	Overrides the text color for the day number
`getDayStyle`	`({ day, state, theme }) => StyleProp<ViewStyle> \| undefined`	Merged on top of the slot view style
`getDayTextStyle`	`({ day, state, theme }) => StyleProp<TextStyle> \| undefined`	Merged on top of the day text style
`getDayContent`	`({ day, state, theme }) => ReactNode \| undefined`	Replaces the default day-number `<Text>`

Priority chain (highest wins): renderDay > getDayContent > default <Text>{day.day}</Text>.

Theming

<AdvancedDatePicker
  theme={{
    primary: '#8B5CF6',
    background: '#1F2937',
    textColor: '#F9FAFB',
    sundayColor: '#EF4444',
    holidayColor: '#34D399',
    rangeBackground: 'rgba(139, 92, 246, 0.15)',
    selectedTextColor: '#FFFFFF',
    dayBorderRadius: 12,
    fontSize: { day: 15, monthHeader: 16, saveButton: 17 },
    spacing: { monthGap: 28 },
    radius: { saveButton: 14, modal: 24 },
  }}
/>

Theme Properties

Property	Default	Description
`primary`	`#2563EB`	Selected date background
`background`	`#FFFFFF`	Calendar background
`textColor`	`#1F2937`	Default text color
`disabledColor`	`#9CA3AF`	Disabled date text
`rangeBackground`	`#EBF0FA`	Range highlight color
`holidayColor`	`#16A34A`	Holiday text color
`sundayColor`	`#DC2626`	Sunday text color
`saturdayColor`	—	Saturday text color (falls back to `textColor`)
`weekendColor`	—	Single color for both Sat & Sun — overrides both `saturdayColor` and `sundayColor` when set
`selectedTextColor`	`#FFFFFF`	Selected date text
`dayBorderRadius`	`99`	Day cell border radius
`monthHeaderColor`	`#2563EB`	Month title color
`weekDayHeaderColor`	`#9CA3AF`	Weekday header color
`dividerColor`	`#E5E7EB`	Divider line color
`fontFamily`	system	Custom font family

`fontSize` (object)

Key	Default	Target
`day`	`14`	Day cell text
`weekDay`	`12`	Week day header row
`monthHeader`	`12`	Month title
`holiday`	`12`	Holiday label text
`saveButton`	`16`	Save button label

`spacing` (object)

Key	Default	Target
`monthGap`	`24`	Vertical gap between months
`weekDayHeaderGap`	`16`	Gap between the week day header divider and the first month
`holidayGap`	`8`	Gap between month grid and holiday list

`radius` (object)

Key	Default	Target
`saveButton`	`12`	Save button border radius
`modal`	`0`	Modal container border radius (full-screen by default)

Custom Locale

import type { Locale } from 'react-native-advanced-date-picker'

const german: Locale = {
  code: 'de',
  dayNamesShort: ['Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa', 'So'],
  monthNames: ['Januar', 'Februar', 'März', 'April', 'Mai', 'Juni',
    'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember'],
  today: 'Heute',
  save: 'Speichern',
  cancel: 'Abbrechen',
  pastDateWarning: 'Sie können kein vergangenes Datum auswählen.',
  warningTitle: 'Warnung',
  ok: 'OK',
  // Optional (v0.2.0):
  selectDate: 'Datum wählen',
  selectRange: 'Zeitraum wählen',
  from: 'Von',
  to: 'Bis',
  clear: 'Löschen',
}

<AdvancedDatePicker locale={german} />

Locale fields

Field	Required	Description
`code`	yes	ISO locale code used for `Intl` formatting (e.g. `'en'`, `'tr'`, `'de'`)
`dayNamesShort`	yes	Short day names, length 7
`monthNames`	yes	Full month names, length 12
`today`	yes	"Today" label
`save`	yes	Save/confirm button text
`cancel`	yes	Cancel button text
`pastDateWarning`	yes	Warning shown when user selects a past date
`warningTitle`	yes	Title for the past-date warning alert
`ok`	yes	OK button text in alerts
`selectDate`	no	Title/placeholder for single date selection
`selectRange`	no	Title/placeholder for range selection
`from`	no	"From" label for range start
`to`	no	"To" label for range end
`clear`	no	Clear/reset button text

Holidays

<AdvancedDatePicker
  holidays={[
    { date: '01-01', label: 'New Year' },
    { date: '12-25', label: 'Christmas', color: '#DC2626', important: true },
    { date: '2026-07-04', label: 'Independence Day' },
  ]}
  showHolidays={true}
/>

Holiday fields

Field	Required	Description
`date`	yes	`'MM-DD'` for recurring yearly, or `'YYYY-MM-DD'` for a specific date
`label`	yes	Display label shown next to/under the date
`color`	no	Override the label text color (falls back to `theme.holidayColor`)
`icon`	no	Optional `ReactNode` rendered alongside the holiday label
`important`	no	Emphasize the holiday (e.g. bold text)

Composable Usage

For advanced customization, import individual components:

import {
  CalendarList,
  DatePickerModal,
  WeekDayHeader,
  MonthHeader,
  DayCell,
  useCalendar,
  en,
  defaultTheme,
} from 'react-native-advanced-date-picker'

const MyCustomCalendar = () => {
  const { calendarData } = useCalendar({
    months: 6,
    locale: 'en',
    holidays: [{ date: '12-25', label: 'Christmas' }],
  })

  return (
    <CalendarList
      mode="single"
      locale={en}
      theme={defaultTheme}
      startDate={null}
      endDate={null}
      onStartDateChange={date => console.log(date)}
      onEndDateChange={date => console.log(date)}
    />
  )
}

Advanced Customization

Slot-based rendering

Replace individual layout pieces without rewriting the whole picker. Every other slot keeps its default.

import { Text, View, TouchableOpacity } from 'react-native'
import { AdvancedDatePicker } from 'react-native-advanced-date-picker'

<AdvancedDatePicker
  mode="range"
  renderMonthHeader={({ month, year, theme }) => (
    <View style={{ paddingVertical: 12, alignItems: 'center' }}>
      <Text style={{ fontSize: 18, fontWeight: '700', color: theme.monthHeaderColor }}>
        {month} {year}
      </Text>
    </View>
  )}
  renderSaveButton={({ onPress, theme, locale }) => (
    <TouchableOpacity
      onPress={onPress}
      style={{
        backgroundColor: theme.primary,
        paddingVertical: 14,
        borderRadius: 16,
        alignItems: 'center',
      }}>
      <Text style={{ color: theme.selectedTextColor, fontWeight: '700' }}>
        {locale.save}
      </Text>
    </TouchableOpacity>
  )}
/>

Per-day callbacks

Compute styles, colors, or custom content from runtime state for specific day cells.

import { View, Text } from 'react-native'

<AdvancedDatePicker
  // Tint weekends purple, keep defaults for everything else.
  getDayColor={({ state }) =>
    state.isSaturday || state.isSunday ? '#8B5CF6' : undefined
  }
  // Add a green dot badge under busy days.
  getDayContent={({ day, state, theme }) => {
    const isBusy = [5, 12, 19].includes(day.day)
    if (!isBusy) return undefined
    return (
      <View style={{ alignItems: 'center' }}>
        <Text style={{ color: state.isSelected ? theme.selectedTextColor : theme.textColor }}>
          {day.day}
        </Text>
        <View style={{
          width: 4,
          height: 4,
          borderRadius: 2,
          backgroundColor: '#16A34A',
          marginTop: 2,
        }} />
      </View>
    )
  }}
/>

Range animation control

By default a range fills cell-by-cell from the start date with a staggered scale animation (native driver). Disable it for instant visual feedback:

<AdvancedDatePicker mode="range" disableAnimation />

Custom Day Rendering (full override)

<AdvancedDatePicker
  renderDay={(day, state) => (
    <View style={{
      width: 40,
      height: 40,
      borderRadius: 20,
      backgroundColor: state.isSelected ? 'purple' : 'transparent',
      alignItems: 'center',
      justifyContent: 'center',
    }}>
      <Text style={{ color: state.isSelected ? 'white' : 'black' }}>
        {day.day}
      </Text>
      {state.isHoliday && <View style={{ width: 4, height: 4, borderRadius: 2, backgroundColor: 'green' }} />}
    </View>
  )}
/>

Inline Mode

<AdvancedDatePicker
  modal={false}
  mode="single"
  startDate={selectedDate}
  onDateChange={({ startDate }) => setSelectedDate(startDate)}
/>

License

MIT

Name		Name	Last commit message	Last commit date
.github		.github
.storybook		.storybook
assets		assets
example		example
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
babel.config.js		babel.config.js
jest.config.js		jest.config.js
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
yarn.lock		yarn.lock

Latest commit

History

Folders and files

Repository files navigation

react-native-advanced-date-picker

Features

What's new in v0.3.0

New selection modes

Preset chips

Per-date badges

Pluggable calendar engines

Headless hook

Workday counter

Accessibility & keyboard

Web support

Migration

Installation

Optional peer dependency

Quick Start

Props

Core props

v0.2.0 — new props

Style escape hatches

Slot render props

Per-day callbacks

Theming

Theme Properties

fontSize (object)

spacing (object)

radius (object)

Custom Locale

Locale fields

Holidays

Holiday fields

Composable Usage

Advanced Customization

Slot-based rendering

Per-day callbacks

Range animation control

Custom Day Rendering (full override)

Inline Mode

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Contributors

Languages

`fontSize` (object)

`spacing` (object)

`radius` (object)