Skip to content

About

A declarative, mobile-first date & range picker for React Native. Single tap or drag-to-select, vertical virtualized months, continuous range bar, full theming, and worklet-driven gestures on the UI thread.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

@daboss2003/react-native-calender-range-picker

Mobile-first, declarative date & range picker for React Native.

  • Single tap or drag to select a range — no separate mode toggle.
  • Vertical, virtualized month list (feels like the iOS Calendar app).
  • Worklet-driven gestures via react-native-reanimated and react-native-worklets — pan events stay on the UI thread.
  • Continuous range bar with rounded endpoints (not pill-per-day).
  • Single theme object — full color control, no dozen-prop API.
  • Zero date-library dependency — pure JS date math.
  • TypeScript first.

Install

npm install @daboss2003/react-native-calender-range-picker \
  react-native-gesture-handler \
  react-native-reanimated \
  react-native-worklets

App setup

  1. Wrap your root in GestureHandlerRootView:
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      {/* ... */}
    </GestureHandlerRootView>
  );
}
  1. Make sure the worklets babel plugin is active.

    • Expo (SDK 50+) — nothing to do. babel-preset-expo already includes react-native-worklets/plugin automatically.

    • Bare React Native (Community CLI) — add it to your babel.config.js:

      module.exports = {
        presets: ['module:@react-native/babel-preset'],
        plugins: ['react-native-worklets/plugin'], // must be last in the plugins array
      };

    react-native-worklets/plugin replaces the old react-native-reanimated/plugin for Reanimated 4+.

Usage

Range mode (default)

import { CalendarRangePicker, type DateRange } from '@daboss2003/react-native-calender-range-picker';

function Screen() {
  return (
    <CalendarRangePicker
      onChange={(value) => {
        const range = value as DateRange;
        console.log(range.start, range.end);
      }}
    />
  );
}

Tap once to set the start, tap again for the end. Long-press + drag to select a range in one gesture.

Single mode

<CalendarRangePicker
  mode="single"
  onChange={(value) => console.log(value as Date)}
/>

With bounds and disabled dates

<CalendarRangePicker
  mode="range"
  minDate={new Date(2026, 0, 1)}
  maxDate={new Date(2026, 11, 31)}
  disabledDates={[new Date(2026, 4, 25)]} // or a predicate (d) => boolean
  onChange={(v) => setRange(v as DateRange)}
/>

Theming

<CalendarRangePicker
  theme={{
    primary: '#FF6B6B',
    onPrimary: '#fff',
    rangeFill: '#FFE3E3',
    text: '#1A1A1A',
    headerText: '#1A1A1A',
    weekdayText: '#8A8A8A',
    todayBorder: '#FF6B6B',
  }}
/>

All theme keys are optional — anything you omit falls back to defaultTheme.

Imperative ref

const ref = useRef<CalendarRangePickerRef>(null);

<CalendarRangePicker ref={ref} />

ref.current?.scrollToToday();
ref.current?.scrollToDate(new Date(2027, 0, 1));
ref.current?.reset();

API

<CalendarRangePicker>

Prop Type Default Description
mode "single" | "range" "range" Selection mode.
initialDate Date — Initial value when mode="single". Optional.
initialRange { start: Date; end: Date } — Initial value when mode="range". Optional.
minDate Date 24 months before today Earliest selectable / visible day.
maxDate Date 24 months after today Latest selectable / visible day.
disabledDates Date[] | (d: Date) => boolean — Disabled days.
onChange (v: Date | DateRange) => void — Fires on completed selection.
theme Partial<Theme> defaultTheme Color overrides (deep-merged).
locale string "en" BCP-47 locale for month/weekday labels.
firstDayOfWeek 0..6 0 0 = Sunday, 1 = Monday, …
monthsBefore number 24 How many months back to render when minDate is omitted.
monthsAfter number 24 How many months forward when maxDate is omitted.
style ViewStyle — Container style.

Ref API

type CalendarRangePickerRef = {
  scrollToDate: (date: Date, animated?: boolean) => void;
  scrollToToday: (animated?: boolean) => void;
  reset: () => void;
};

Theme

type Theme = {
  primary: string;       // selected day fill + today ring
  onPrimary: string;     // text on selected day
  rangeFill: string;     // continuous range bar color
  text: string;          // in-month day text
  mutedText: string;     // spill-over day text (prev/next month)
  disabled: string;      // disabled day text
  background: string;    // overall background
  headerText: string;    // "May 2026" header
  weekdayText: string;   // "Mon Tue Wed..." row
  todayBorder: string;   // ring around today (unselected)
};

How it works

  • Months are rendered in a vertical, virtualized Animated.SectionList. Only ~3 months stay mounted at a time.
  • Each Day cell is React.memo'd — re-renders only when its own selection state changes.
  • Pan gestures use Reanimated 4 worklets: hit-testing (finger → cell → date) runs on the UI thread. Only when the targeted cell changes does it schedule a JS update via scheduleOnRN.
  • No date library — dateUtils.ts provides everything needed (~70 lines).

Example app

A runnable Expo example lives in example/. From the repo root:

cd example
npm install
npm run ios     # builds a native dev client (first run: ~5–15 min)

Why run:ios instead of start + Expo Go? Reanimated + Worklets + Gesture Handler with the New Architecture require their native modules to be linked into a custom dev client. The vanilla Expo Go binary does not load RNGestureHandlerModule / WorkletsModule under bridgeless mode, so it will red-screen at startup. A one-time expo run:ios build fixes this; subsequent reloads use npm start and are instant.

Heads-up: avoid duplicate copies of native modules

If you consume this library from a sibling directory via "file:.." (or in a monorepo / workspace setup), make sure your library directory does not have its own node_modules containing different versions of react-native-gesture-handler, react-native-reanimated, or react-native-worklets. Two copies = the JS side imports one, the native binary registered the other, and you get:

TurboModuleRegistry.getEnforcing(...): 'RNGestureHandlerModule' could not be found.

Fix: either rm -rf <library-root>/node_modules so the app's copy is the only one, or pin matching versions in your consumer app's package.json overrides. The gesture-handler troubleshooting docs cover the same scenario.

License

MIT © daboss2003

About

A declarative, mobile-first date & range picker for React Native. Single tap or drag-to-select, vertical virtualized months, continuous range bar, full theming, and worklet-driven gestures on the UI thread.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages