react-native-calendars is a comprehensive and highly customizable set of calendar components designed for React Native applications. It provides a variety of views including a standard month calendar, a scrollable list of calendars (CalendarList), an agenda view combining a calendar with an event list, and expandable week views. The library is actively maintained with frequent releases, often multiple times a week or month, indicating rapid development and responsiveness to bug fixes and feature requests. The current stable version is 1.1314.0. Key differentiators include extensive styling options, support for marking specific dates with various styles (dots, periods, custom backgrounds), and accessibility features. It aims to offer a robust solution for displaying and interacting with date information in mobile applications without requiring complex native module linking beyond standard React Native setup.
npm install react-native-calendarsVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to render a basic calendar component, handle day selection events, apply various custom date markings, and set a custom theme. It also includes basic localization setup.
Pin your dependency version (e.g., `"react-native-calendars": "1.x.y"` or `"~1.x.y"`) and review changelogs before upgrading. Implement robust testing for calendar-related features, especially after updates.
Optimize `markedDates` generation. Memoize the `markedDates` object using `React.useMemo` if it doesn't change frequently. Profile performance on target devices. Ensure the object structure strictly adheres to the documentation for each marking type (dot, period, custom). Consider pagination if displaying extremely large date ranges.
If `react-native-safe-area-context` is required for your application (e.g., for `SafeAreaView`), ensure it's explicitly installed and linked in your project: `npm install react-native-safe-area-context` and then run `npx pod-install` for iOS.
Utilize the `theme` prop for global styling (colors, fonts). For more granular control, use `style` props on individual components, but be prepared to override default styles aggressively or use `StyleSheet.absoluteFill` with `zIndex` for complex custom overlays.
Thoroughly test with screen readers (e.g., VoiceOver on iOS, TalkBack on Android). Provide meaningful `accessibilityLabel` props for interactive elements and custom date renderings. Pay attention to semantic roles for complex custom components.
Ensure that any data you iterate over to render components (e.g., event items in `Agenda`, custom day components) has a unique identifier, and assign it to the `key` prop: `<MyComponent key={item.id} />` or use `keyExtractor` for `FlatList` based components to provide unique keys for each rendered item.Verify the structure of your `markedDates` object (it should be `{ 'YYYY-MM-DD': { /* marking data */ } }` ) and `items` object (it should be `{ 'YYYY-MM-DD': [ /* event objects */ ] }` ) against the library's documentation. Ensure these props are always initialized to an empty object `{}` rather than `null` or `undefined` if no data is available.Always create a *new* object for props like `markedDates` and `items` when their content changes. For example, use spread syntax (`{ ...oldMarkedDates, [newDate]: newMarking }`) or `Object.assign` to ensure React detects a prop change and triggers a re-render. Similarly, for arrays, use `.map()`, `.filter()`, or spread syntax (`[...oldArray, newItem]`) instead of `.push()` or direct modification.No dependency data recorded yet.