react-native-calendars: Calendar Components for iOS and Android

What react-native-calendars Provides and Why Pure JS Matters

react-native-calendars provides calendar UI components for React Native applications that run on both iOS and Android. The README describes it as a declarative, cross-platform module. The most significant design decision is that the library is implemented entirely in JavaScript with no native code. This means no native module linking is required after installation, and the library is compatible with Expo and Create React Native App projects without ejecting. For teams using Expo's managed workflow, this removes a common friction point. The three main components are Calendar for a single-month view, CalendarList for a scrollable list of months, and Agenda for an agenda view that shows items below a calendar header. The library uses recyclerlistview for the CalendarList component to handle large numbers of months efficiently.

Installing and Importing the Components

Installation uses yarn or npm. The README uses the yarn command.

$ yarn add react-native-calendars

Because the library has no native modules, no pod install or gradle linking step is needed after installation. Import the components from the package root.

import {Calendar, CalendarList, Agenda} from 'react-native-calendars';

A minimal Calendar component renders with no required props. The onDayPress callback receives a day object when the user taps a date, which includes the date string in YYYY-MM-DD format, the day number, month, year, and timestamp. The README also mentions that examples have been published on Expo, which lets you preview the component behavior before installation.

Date Marking Modes: Dot, Period, Multi-Dot, and Custom

The markedDates prop accepts an object where each key is a date string and the value is a marking configuration. The library supports five marking types. Dot marking places a small dot below a date, typically used for events. Multi-dot marking allows multiple colored dots on a single date. Period marking draws a colored bar across a date range. Multi-period marking supports multiple overlapping period bars. Custom marking gives full control over the rendered date component. The README provides a code example showing how to highlight a selected date with a background color and disable touch events on it.

<Calendar
  onDayPress={day => {
    console.log('selected day', day);
  }}
  markedDates={{
    '2012-03-01': {selected: true, marked: true, selectedColor: 'blue'},
    '2012-03-02': {marked: true},
    '2012-03-03': {selected: true, marked: true, selectedColor: 'blue'}
  }}
/>

The marking type is set via the markingType prop on the Calendar component, since the prop object format differs between types.

Locale Configuration and Theme Customization

The library exports a LocaleConfig object for configuring month names, short month names, day names, and day name abbreviations for any locale. The README provides a French locale example that sets all these arrays. The theme prop accepts a flat object with keys for calendar background, text section title color, selected day background color, selected day text color, today text color, day text color, and disabled text color. This covers the most common visual adjustments without subclassing. The style prop accepts standard React Native style properties including borderWidth, borderColor, and height, which controls the calendar's container. Accessibility is listed as a supported feature in the README, though no specific API details are provided in the text. Automatic date formatting for different locales is also listed as a feature, separate from the manual LocaleConfig mechanism.

The CalendarList and Agenda Components

CalendarList renders a scrollable, semi-infinite list of months. The README describes it as a scrollable calendar. It uses recyclerlistview internally for performance when rendering many months. The Agenda component combines a calendar header with a scrollable list of items below it. Items are keyed by date string, and the Agenda connects a date selection in the header to the corresponding item list. The README shows example screens but does not describe the full Agenda API in its text; the official documentation at wix.github.io/react-native-calendars/docs/Intro covers the complete prop set. An ExpandableCalendar component is mentioned in the README's related searches and community context, and an expandable calendar feature is referenced in the search data under react-native-calendars expandablecalendar, though the README itself does not document it in the text provided.

Limitations: No Week View, Dependent on xdate, Sparse Long-Term Updates

The package depends on xdate for date handling, a library that has not been actively developed for years. This is a third-party dependency risk for long-running projects. The library has no built-in week view component. If your design requires a week-view calendar similar to Google Calendar, react-native-calendars does not provide it out of the box. The last push to the repository was on 2026-04-23, about five months before this article. The most recent npm release was 1.1314.0 on 2026-01-29. The gap between release and last push suggests development activity has slowed. The library is pure JavaScript, which is an advantage for Expo compatibility but can also mean that platform-specific native optimizations are not available. The README advises contributors not to format files to keep the review process simple, which signals that the review process prioritizes stability over modernization.

react-native-calendars versus react-native-big-calendar

react-native-big-calendar is an alternative calendar library for React Native that focuses on week and day views with event display similar to Google Calendar or Apple Calendar. It targets applications that need to display timed events across a day or week grid. react-native-calendars focuses on month and agenda views with date selection and marking. The two serve different display patterns: react-native-calendars is the right choice for date pickers, booking flows, and month-based schedules, while react-native-big-calendar is better suited for time-blocking and event scheduling interfaces. Both are open-source. react-native-calendars has the longer history and more extensive marking API; react-native-big-calendar has the week and day view that react-native-calendars lacks.

Editorial conclusion

react-native-calendars is the right choice for React Native projects that need customizable calendar display, date selection, or an Agenda view without writing native code. It is not the right choice if you need a week-view layout, complex recurring event handling, or a library that tracks the latest React Native releases immediately. Before adding it to an Expo project, verify that the current package version is compatible with your Expo SDK version, since the package.json in the repository shows version 1.22.0 while the npm registry may be at a later release.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. wix/react-native-calendars on GitHub