react-native-calendars

What is react-native-calendars?

The react-native-calendars package provides a set of customizable calendar components for React Native applications. It allows developers to create various types of calendar views, including agenda views, calendar lists, and marked dates. The package is highly flexible and supports a wide range of customization options, making it suitable for different use cases such as scheduling, event planning, and date selection.

What are react-native-calendars's main functionalities?

Basic Calendar

This code demonstrates how to create a basic calendar using the react-native-calendars package. It includes various customization options such as setting the initial visible month, minimum and maximum selectable dates, handling day and month changes, and hiding navigation arrows.

import { Calendar } from 'react-native-calendars';

const MyCalendar = () => (
  <Calendar
    // Initially visible month. Default = Date()
    current={'2023-10-01'}
    // Minimum date that can be selected, dates before minDate will be grayed out. Default = undefined
    minDate={'2023-05-10'}
    // Maximum date that can be selected, dates after maxDate will be grayed out. Default = undefined
    maxDate={'2023-12-31'}
    // Handler which gets executed on day press. Default = undefined
    onDayPress={(day) => {console.log('selected day', day)}}
    // Month format in calendar title. Formatting values: http://arshaw.com/xdate/#Formatting
    monthFormat={'yyyy MM'}
    // Handler which gets executed when visible month changes in calendar. Default = undefined
    onMonthChange={(month) => {console.log('month changed', month)}}
    // Hide month navigation arrows. Default = false
    hideArrows={true}
    // Replace default arrows with custom ones (direction can be 'left' or 'right')
    renderArrow={(direction) => (<Arrow />)}
    // Do not show days of other months in month page. Default = false
    hideExtraDays={true}
    // If hideArrows=false and hideExtraDays=false do not switch month when tapping on greyed out day from another month that is visible in calendar page. Default = false
    disableMonthChange={true}
    // Handler which gets executed when press arrow icon left. It receive a callback can go back month
    onPressArrowLeft={subtractMonth => subtractMonth()}
    // Handler which gets executed when press arrow icon right. It receive a callback can go next month
    onPressArrowRight={addMonth => addMonth()}
    // Disable left arrow. Default = false
    disableArrowLeft={true}
    // Disable right arrow. Default = false
    disableArrowRight={true}
    // Disable all touch events for disabled days. can be override with disableTouchEvent in markedDates
    disableAllTouchEventsForDisabledDays={true}
    // Replace default month and year title with custom one. the function receive a date as parameter
    renderHeader={(date) => {/*Return JSX*/}}
    // Enable the option to swipe between months. Default = false
    enableSwipeMonths={true}
  />
);

Agenda View

This code demonstrates how to create an agenda view using the react-native-calendars package. The agenda view displays a list of items for each day, allowing users to see their schedule at a glance. The component supports various customization options, including rendering custom items, days, and empty dates.

import { Agenda } from 'react-native-calendars';

const MyAgenda = () => {
  const items = {
    '2023-10-22': [{name: 'item 1 - any js object'}],
    '2023-10-23': [{name: 'item 2 - any js object'}],
    '2023-10-24': [],
    '2023-10-25': [{name: 'item 3 - any js object'}, {name: 'any js object'}]
  };

  return (
    <Agenda
      items={items}
      // Callback that gets called when items for a certain month should be loaded (month became visible)
      loadItemsForMonth={(month) => {console.log('trigger items loading')}}
      // Callback that fires when the calendar is opened or closed
      onCalendarToggled={(calendarOpened) => {console.log(calendarOpened)}}
      // Callback that gets called on day press
      onDayPress={(day) => {console.log('day pressed')}}
      // Callback that gets called when day changes while scrolling agenda list
      onDayChange={(day) => {console.log('day changed')}}
      // Initially selected day
      selected={'2023-10-16'}
      // Minimum date that can be selected, dates before minDate will be grayed out. Default = undefined
      minDate={'2023-05-10'}
      // Maximum date that can be selected, dates after maxDate will be grayed out. Default = undefined
      maxDate={'2023-12-31'}
      // Max amount of months allowed to scroll to the past. Default = 50
      pastScrollRange={12}
      // Max amount of months allowed to scroll to the future. Default = 50
      futureScrollRange={12}
      // Specify how each item should be rendered in agenda
      renderItem={(item, firstItemInDay) => {return (<View />);}}
      // Specify how each date should be rendered. day can be undefined if the item is not first in that day.
      renderDay={(day, item) => {return (<View />);}}
      // Specify how empty date content with no items should be rendered
      renderEmptyDate={() => {return (<View />);}}
      // Specify how agenda knob should look like
      renderKnob={() => {return (<View />);}}
      // Specify what should be rendered instead of ActivityIndicator
      renderEmptyData={() => {return (<View />);}}
      // If disabledByDefault={true} dates flagged as not disabled will be enabled. Default = false
      disabledByDefault={true}
      // If hideKnob={true} calendar knob will not be displayed. Default = false
      hideKnob={true}
      // Agenda theme
      theme={{
        agendaDayTextColor: 'yellow',
        agendaDayNumColor: 'green',
        agendaTodayColor: 'red',
        agendaKnobColor: 'blue'
      }}
      // Agenda container style
      style={{}}
    />
  );
};

Marked Dates

This code demonstrates how to mark specific dates on the calendar using the react-native-calendars package. The marked dates feature allows developers to highlight important dates, such as events or deadlines, with different styles and colors.

import { Calendar } from 'react-native-calendars';

const MyMarkedDatesCalendar = () => (
  <Calendar
    // Collection of dates that have to be marked. Default = {}
    markedDates={{
      '2023-10-16': {selected: true, marked: true, selectedColor: 'blue'},
      '2023-10-17': {marked: true},
      '2023-10-18': {disabled: true, disableTouchEvent: true}
    }}
    // Date marking style [simple/period/multi-dot/custom]. Default = 'simple'
    markingType={'multi-dot'}
  />
);

Other packages similar to react-native-calendars

react-native-calendar-picker

react-native-calendar-picker is a simple and flexible calendar picker component for React Native. It provides basic calendar functionalities such as date selection and customization options. Compared to react-native-calendars, it is more lightweight but offers fewer advanced features like agenda views and complex date marking.

react-native-calendario

react-native-calendario is a customizable calendar component for React Native that supports date range selection. It is designed to be simple and easy to use, with a focus on date range picking. While it offers a clean and straightforward interface, it lacks some of the advanced features and customization options available in react-native-calendars.

react-native-big-calendar

react-native-big-calendar is a calendar component for React Native that provides a large, full-featured calendar view. It supports various views such as month, week, and day, and allows for event scheduling and customization. Compared to react-native-calendars, it offers more comprehensive event management features but may be more complex to integrate and customize.

README

React Native Calendars 🗓️ 📆

A declarative cross-platform React Native calendar component for iOS and Android.

This module includes information on how to use this customizable React Native calendar component.

The package is compatible with both Android and iOS

Official documentation

This README provides basic examples of how to get started with react-native-calendars. For detailed information, refer to the official documentation site.

Features ✨

• Pure JS. No Native code required
• Date marking - dot, multi-dot, period, multi-period and custom marking
• Customization of style, content (days, months, etc) and dates
• Detailed documentation and examples
• Swipeable calendar with flexible custom rendering
• Scrolling to today, selecting dates, and more
• Allowing or blocking certain dates
• Accessibility support
• Automatic date formatting for different locales

Try it out ⚡

You can run a sample module using these steps:

$ git clone [e-mail]:wix/react-native-calendars.git

$ cd react-native-calendars

$ yarn install

$ cd ios && pod install && cd ..

$ react-native run-ios

You can check example screens source code in example module screens

This project is compatible with Expo/CRNA (without ejecting), and the examples have been published on Expo

Getting Started 🔧

Here's how to get started with react-native-calendars in your React Native project:

Install the package:

$ yarn add react-native-calendars

RN Calendars is implemented in JavaScript, so no native module linking is required.

Usage 🚀

Basic usage examples of the library

For detailed information on using this component, see the official documentation site

Importing the Calendar component

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

Use the Calendar component in your app:

<Calendar
  onDayPress={day => {
    console.log('selected day', day);
  }}
/>

Some Code Examples

Here are a few code snippets that demonstrate how to use some of the key features of react-native-calendars:

Creating a basic calendar with default settings:

import React, {useState} from 'react';
import {Calendar, LocaleConfig} from 'react-native-calendars';

const App = () => {
  const [selected, setSelected] = useState('');

  return (
    <Calendar
      onDayPress={day => {
        setSelected(day.dateString);
      }}
      markedDates={{
        [selected]: {selected: true, disableTouchEvent: true, selectedDotColor: 'orange'}
      }}
    />
  );
};

export default App;

Customize the appearance of the calendar:

<Calendar
  // Customize the appearance of the calendar
  style={{
    borderWidth: 1,
    borderColor: 'gray',
    height: 350
  }}
  // Specify the current date
  current={'2012-03-01'}
  // Callback that gets called when the user selects a day
  onDayPress={day => {
    console.log('selected day', day);
  }}
  // Mark specific dates as marked
  markedDates={{
    '2012-03-01': {selected: true, marked: true, selectedColor: 'blue'},
    '2012-03-02': {marked: true},
    '2012-03-03': {selected: true, marked: true, selectedColor: 'blue'}
  }}
/>

Configuring the locale:

import {LocaleConfig} from 'react-native-calendars';
import React, {useState} from 'react';
import {Calendar, LocaleConfig} from 'react-native-calendars';

LocaleConfig.locales['fr'] = {
  monthNames: [
    'Janvier',
    'Février',
    'Mars',
    'Avril',
    'Mai',
    'Juin',
    'Juillet',
    'Août',
    'Septembre',
    'Octobre',
    'Novembre',
    'Décembre'
  ],
  monthNamesShort: ['Janv.', 'Févr.', 'Mars', 'Avril', 'Mai', 'Juin', 'Juil.', 'Août', 'Sept.', 'Oct.', 'Nov.', 'Déc.'],
  dayNames: ['Dimanche', 'Lundi', 'Mardi', 'Mercredi', 'Jeudi', 'Vendredi', 'Samedi'],
  dayNamesShort: ['Dim.', 'Lun.', 'Mar.', 'Mer.', 'Jeu.', 'Ven.', 'Sam.'],
  today: "Aujourd'hui"
};

LocaleConfig.defaultLocale = 'fr';

const App = () => {
  const [selected, setSelected] = useState('');

  return (
    <Calendar
      onDayPress={day => {
        setSelected(day.dateString);
      }}
      markedDates={{
        [selected]: {selected: true, disableTouchEvent: true, selectedDotColor: 'orange'}
      }}
    />
  );
};

export default App;

Adding a global theme to the calendar:

    <Calendar
      style={{
        borderWidth: 1,
        borderColor: 'gray',
        height: 350,
      }}
      theme={{
        backgroundColor: '#ffffff',
        calendarBackground: '#ffffff',
        textSectionTitleColor: '#b6c1cd',
        selectedDayBackgroundColor: '#00adf5',
        selectedDayTextColor: '#ffffff',
        todayTextColor: '#00adf5',
        dayTextColor: '#2d4150',
        textDisabledColor: '#dd99ee'
      }}
    </Calendar>

Customized Calendar Examples

Calendar

Dot marking

Multi-Dot marking

Period Marking

Multi-Period marking

Custom marking

Date loading indicator

Scrollable semi-infinite calendar

Horizontal calendar

Agenda

Authors

• Tautvilas Mecinskas - Initial code - @tautvilas
• Katrin Zotchev - Initial design - @katrin_zot

See also the list of contributors who participated in this project.

Contributing

We welcome contributions to react-native-calendars.

If you have an idea for a new feature or have discovered a bug, please open an issue.

Please yarn test and yarn lint before pushing changes.

Don't forget to add a title and a description explaining the issue you're trying to solve and your proposed solution.

Screenshots and Gifs are VERY helpful to add to the PR for reviews.

Please DO NOT format the files - we're trying to keep a unified syntax and keep the reviewing process fast and simple.

License

React Native Calendars is MIT licensed