{"id":11763,"library":"react-native-calendars","title":"React Native Calendars","description":"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.","status":"active","version":"1.1314.0","language":"javascript","source_language":"en","source_url":"https://github.com/wix/react-native-calendars","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-native-calendars","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-calendars","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-calendars","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Main component for a standard month view calendar. Supports various props for customization and date marking.","wrong":"const Calendar = require('react-native-calendars')","symbol":"Calendar","correct":"import { Calendar } from 'react-native-calendars'"},{"note":"Used for a vertically scrollable list of calendars, often for implementing infinite scrolling month views. Accepts similar props to `Calendar`.","wrong":"import CalendarList from 'react-native-calendars'","symbol":"CalendarList","correct":"import { CalendarList } from 'react-native-calendars'"},{"note":"Combines a calendar view with a list of events for selected dates, providing a complete agenda experience. Requires an `items` prop for event data.","wrong":"import { agenda } from 'react-native-calendars'","symbol":"Agenda","correct":"import { Agenda } from 'react-native-calendars'"},{"note":"Provides utilities for configuring localization settings for month names, day names, and 'today' labels globally for all calendar components.","symbol":"LocaleConfig","correct":"import { LocaleConfig } from 'react-native-calendars'"}],"quickstart":{"code":"import React, { useState, useCallback } from 'react';\nimport { SafeAreaView, StyleSheet, Text, View } from 'react-native';\nimport { Calendar, LocaleConfig } from 'react-native-calendars';\n\n// Configure localization (optional)\nLocaleConfig.locales['en'] = {\n  monthNames: ['January','February','March','April','May','June','July','August','September','October','November','December'],\n  monthNamesShort: ['Jan.','Feb.','Mar.','Apr.','May.','Jun.','Jul.','Aug.','Sep.','Oct.','Nov.','Dec.'],\n  dayNames: ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday'],\n  dayNamesShort: ['Sun.','Mon.','Tue.','Wed.','Thu.','Fri.','Sat.'],\n  today: 'Today'\n};\nLocaleConfig.defaultLocale = 'en';\n\nconst App = () => {\n  const [selected, setSelected] = useState('');\n\n  const onDayPress = useCallback((day) => {\n    setSelected(day.dateString);\n  }, []);\n\n  // Define marked dates for special styling\n  const markedDates = {\n    [selected]: {\n      selected: true,\n      disableTouchEvent: true,\n      selectedColor: 'orange', \n      selectedTextColor: 'white'\n    },\n    '2026-04-20': {dots: [{key: 'vacation', color: 'blue', selectedDotColor: 'blue'}]},\n    '2026-04-21': {marked: true, dotColor: 'red'},\n    '2026-04-22': {selected: true, marked: true, selectedColor: 'purple', customStyles: { text: { color: 'white' } }}\n  };\n\n  return (\n    <SafeAreaView style={styles.container}>\n      <Text style={styles.title}>My Calendar App</Text>\n      <Calendar\n        onDayPress={onDayPress}\n        markedDates={markedDates}\n        enableSwipeMonths={true}\n        hideExtraDays={true}\n        showWeekNumbers={true}\n        firstDay={1} // Monday as first day of the week\n        style={styles.calendar}\n        theme={{\n          selectedDayBackgroundColor: '#00adf5',\n          todayTextColor: '#00adf5',\n          arrowColor: 'orange',\n          indicatorColor: 'orange',\n          textMonthFontWeight: 'bold',\n          textDayHeaderFontWeight: '500',\n          backgroundColor: '#ffffff'\n        }}\n      />\n      {selected && <Text style={styles.selectedDayText}>Selected day: {selected}</Text>}\n    </SafeAreaView>\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    backgroundColor: '#f5fcff',\n    paddingTop: 50, // Ensure content is below status bar\n  },\n  title: {\n    fontSize: 24,\n    textAlign: 'center',\n    marginBottom: 20,\n    fontWeight: 'bold',\n    color: '#333',\n  },\n  calendar: {\n    borderWidth: 1,\n    borderColor: '#ddd',\n    borderRadius: 10,\n    marginHorizontal: 15,\n    padding: 10,\n    elevation: 3, // Android shadow\n    shadowColor: '#000', // iOS shadow\n    shadowOffset: { width: 0, height: 2 },\n    shadowOpacity: 0.1,\n    shadowRadius: 4,\n  },\n  selectedDayText: {\n    fontSize: 18,\n    textAlign: 'center',\n    marginTop: 30,\n    fontWeight: '600',\n    color: '#00adf5',\n  },\n});\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"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.","message":"The library undergoes very frequent updates, often multiple times a week. While this indicates active development, it means developers should frequently review changelogs and consider precise dependency pinning to avoid unexpected behavior changes or regressions in minor versions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"Managing complex `markedDates` objects, especially with many dates or dynamic custom styling functions, can lead to performance degradation, particularly on lower-end devices or with very large date ranges. Incorrectly formatted `markedDates` can also cause render errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"Version 1.1314.0 removed `react-native-safe-area-context` as an unused dependency. While this is a cleanup, if your project implicitly relied on this library being present in `node_modules` through `react-native-calendars`, you might encounter runtime issues if `react-native-safe-area-context` is not explicitly installed and linked in your project.","severity":"breaking","affected_versions":">=1.1314.0"},{"fix":"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.","message":"Customizing the appearance of calendar components can sometimes be challenging due to the nested structure of React Native components and potential style conflicts. Achieving pixel-perfect designs often requires deep inspection of the component hierarchy or careful use of provided `theme` and `style` props.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"Ensuring full accessibility across all custom calendar implementations (e.g., custom headers, day renderings) requires careful attention to `accessibilityLabel`, `accessible`, and `role` props, which can be easily overlooked, leading to poor user experience for assistive technology users.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"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.","cause":"This warning typically occurs when rendering iterated components within `CalendarList`, `AgendaList`, or `WeekCalendar` without providing a stable, unique `key` prop for each item. The changelog for 1.1313.0 specifically mentions a fix for `WeekCalendar` related to this.","error":"Warning: Each child in a list should have a unique \"key\" prop."},{"fix":"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.","cause":"This usually indicates that the `markedDates` prop for `Calendar` / `CalendarList` or the `items` prop for `Agenda` is not in the expected data structure (e.g., `markedDates` is not an object, or `items` is `null`/`undefined` when the component expects an object with date string keys).","error":"TypeError: Cannot read property 'map' of undefined (or similar errors related to `markedDates` or `items` prop)"},{"fix":"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.","cause":"React performs shallow comparisons on props. If you mutate an existing object (e.g., `markedDates`) directly rather than creating a new object with the updated data, React won't detect the change and won't trigger a re-render of the component.","error":"Calendar/Agenda view does not update visually after changing date data (e.g., `markedDates`, `items`) in state."}],"ecosystem":"npm"}