react-native-big-calendar: a Google Calendar style view for React Native

A grid that looks like the calendar people already use

react-native-big-calendar is a cross-platform gcal and Outlook like calendar component for React Native, and the whole positioning is in that phrase. It is not a date picker and not a scheduling widget. It is a rendering of a schedule in the layout people recognise from the tools they use every day.

That matters because calendar UI is one of the few areas where a bespoke design is almost always worse than the familiar one. A week view with a time gutter on the left, a header row of days across the top, and events positioned by time is a layout the user has already learned, and reproducing it is the whole job.

The feature list is four entries and they are about the shape of the thing. It runs on the Web, iOS and Android with the power of React. It is fully written in TypeScript, and type-safe. You can provide your own theme and pass your own component to render. And it is lightweight, about 9KB minified and gzipped, with dayjs and calendarize as its dependencies.

That last point is what makes it interesting for a React Native project. A calendar component that drags in a date library, a gesture library, a state manager and a rendering library ends up being the heaviest dependency in your app. This one has two runtime dependencies and a size that is smaller than most of its competitors' transitive trees.

The demo is published at react-native-big-calendar.vercel.app, and the repository has an rndemo directory with a synced build, which is the fastest way to see the component running without setting up a native project.

Installing it, and the peer dependencies people forget

The install is a single npm command:

npm install --save react-native-big-calendar

or with yarn:

yarn add react-native-big-calendar

The next step is the one that catches people. The package declares react and react-native as peer dependencies with a wildcard version, so npm will not install them for you, and the documentation asks you to ensure the peer dependencies are installed:

npm install react react-native

If you are on the Web you also need react-native-web, installed the same way, and the documentation points at the official react-native-web installation guide for the details of what that involves for your bundler.

TypeScript users have one more step. The package uses @types/react and @types/react-native internally, so the documentation asks you to make sure both are installed:

npm install --save-dev @types/react @types/react-native

There is no native module to link, no pod install step, and no configuration file. That is the practical advantage of a component built from React Native primitives rather than from native views: it runs wherever React Native runs, including the Web, with nothing to build.

The version in the package manifest is 4.19.0, and the published entry points are a CommonJS build at build/index.js, an ES module at build/index.es.js with the module field pointing at the same file, and type declarations at build/index.d.ts.

The props are where the design decisions live

The API documentation gives the full CalendarProps interface, and reading it tells you what the component is willing to do and what it leaves to you.

The required props are few: events, which is an array of ICalendarEvent, and height. Everything else is optional and defaults to something sensible. The event type is generic, so you can extend ICalendarEvent with your own fields and keep them typed through the component.

The layout props are the interesting group. overlapOffset controls how much overlapping events are shifted so both remain visible. hourRowHeight sets the height of an hour row, so the calendar can be as dense or as readable as you want. ampm switches the clock to a twelve-hour format. minHour and maxHour clip the visible range of the day, and timeslots sets how many slots each hour is divided into. showTime toggles the time gutter. hideNowIndicator removes the current-time line. scrollOffsetMinutes sets where the view opens, which matters if your working day starts at nine.

The mode prop selects the view, and with it come the month-specific props: eventMinHeightForMonthView, sortedMonthView, showAdjacentMonths and moreLabel for the overflow count. The month view is where the extra props accumulate, and where the component is least flexible, because a month grid cannot position events by time.

Then there are the render props, and these are the ones that make it adaptable. renderEvent takes your event and the touchable props and returns a ReactElement, so you can draw an event cell however you like. renderHeader and renderHeaderForMonthView replace the header components. renderMultiDayEventPadding lets you control the padding on events that span days.

And then accessibility, which is unusually thorough for a calendar component. There is a separate prop for the event cell, the all-day event cell, the calendar cell, the header container, the header cell and the body container, and for the month view's calendar cell. That is a deliberate, repeated structure rather than one catch-all, which tells you the author thought about screen readers per region of the UI.

The v5 experiment was dropped, and the README says so plainly

The most useful thing in this repository is a notice at the top, and it is unusual for a project to publish it in this form.

The notice states that react-native-big-calendar v4 is the stable, actively maintained release line. Development of the experimental v5 implementation, described as the swipe and gesture-driven rewrite that was published under the next npm tag, has been discontinued. Its code is preserved on the v5 branch for reference only.

Then it points elsewhere. If you are looking for a modern, gesture-driven calendar with virtualization and drag-and-drop, it suggests super-calendar, a separate ground-up library by afonsojramos with a different API, and it is careful to say that super-calendar is not a fork and not an official v5, but that it covers the direction the v5 experiment was aiming for.

This is worth pausing on, because a version number is a promise and a discontinued rewrite is an admission that the promise was not kept. A project that says plainly that its next generation was abandoned, that the branch remains for reference, and that a different library covers the same ground is being more useful to an adopter than a project quietly leaving the next tag to rot.

The release history backs the story. There are two v5.0.0 beta tags, beta.11 and beta.12, both published on 2026-01-28 within about an hour of each other, and before them v4.19.0 from 2025-11-01. So the v5 line was iterated on in January 2026 and then stopped, while the v4 line continued. The last push to the repository was on 2026-10-13.

The consequence for anyone choosing between this and the alternative is that the two libraries are not on the same trajectory. This one is the stable grid view with a deep prop surface. The other is the gesture-driven replacement with a different API and a different author.

A note from the maintainer about debugging on three platforms

The repository contains a section headed with a plea for help debugging the component, and it is the most honest passage in the documentation.

The maintainer describes the difficulty of debugging a library across three platforms. The workflow is to develop with the Web version first and then confirm with real devices. The maintainer's own machine is Linux with an Android phone, so Android is easy to test, while debugging on iOS means bringing a MacBook Pro from the garage and connecting a family iPhone to it. Every launch of that machine requires updating Xcode or performing a full system update, which makes starting a debug session slow enough that iOS testing gets skipped.

The conclusion the maintainer draws is that since React Native works better on iOS than Android, there is probably a bug on iOS, and help debugging it would be appreciated.

Two things follow from this. The first is a caution for adopters: a component maintained by one person, with the maintainer's own device coverage being Linux plus Android and iOS covered intermittently, is going to have platform-specific problems, and the maintainer says so rather than claiming parity.

The second is about the project's shape. The README also asks for help with debugging in a way that suggests a small project with a lot of surface area: three platforms, Web included, a month view and a week view, custom render props, and a theme system.

The release history supports that reading too. The v4 line reached 4.19.0, which is a lot of patch releases for a component, and the CHANGELOG.md at the root of the repository is where you would look for the platform-specific history the maintainer refers to.

The build and the repository, and how the package is produced

The build is Rollup with TypeScript, and the scripts in the package manifest show the whole pipeline.

The build is npm-run-all over build:clean and build:ts. The clean step is rimraf build/, and the TypeScript step runs env NODE_ENV=production rollup -c. The prepublish script runs the build, and there is a watch mode at rollup -cw. The rollup.config.js at the root of the repository holds the configuration.

Testing is jest, with a jest.config.js at the root, and the swc/jest combination in the dev dependencies is why the tests run quickly. The lint setup is eslint over src and stories with the TypeScript parser and plugin, and formatting is prettier over src and stories. The stories/ directory is the Storybook source, and the .storybook/ directory holds the configuration, with the storybook script starting it on port 7007 and the build-storybook script producing a static build into .storybook-build. Both Storybook scripts set NODE_OPTIONS=--openssl-legacy-provider, which is the flag you need for Storybook on newer Node versions.

The rndemo directory is a demo application with the built package copied into it, and the sync-rndemo script does yarn build and copies the build output there. So the demo you can run is always the current build rather than a published artifact, which is what you want when you are checking whether a change works on a device.

The remaining top-level entries are conventional: .babelrc, .eslintrc.yml, prettier.config.js, tsconfig.json and tsconfig.prod.json, a tslint.json, an .npmignore, .nvmrc and a yarn.lock, plus CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md and the MIT LICENSE file.

Where react-native-big-calendar is the wrong tool

The first limit is the one the project itself identifies. If you need drag-and-drop, gesture-driven rescheduling or virtualization over a long list of events, this library does not do it, and the v5 work that would have is discontinued. You would be starting from the v4 branch and writing that yourself, or you would be choosing super-calendar instead.

The second is that it renders events but does not manage them. There is no editing model, no persistence, no conflict handling and no state management. It takes an array of events and draws them. Whatever produces that array, and whatever happens when a user drags something, is your code.

The third is the three-platform debugging cost, which the maintainer documents more candidly than most projects do. The component uses React Native primitives so it needs no native linking, which is a genuine advantage, and it also means the rendering differences between platforms are yours to handle through the style props and the render props. The style prop list is long, with separate entries for the event cell, the all-day event cell, the calendar cell, the header container, the header cell and the body container, and the month view has its own subset.

The fourth is the peer dependency on react-native-web for Web use. If you are not already in a react-native-web setup, adding one to get a calendar to render in a browser is a significant decision that the small size of this component will not offset.

The fifth is the maintenance concentration. One author, a component with a large prop surface, and a README that asks for help debugging iOS. The v4 line is described as actively maintained and the last push was on 2026-10-13, but the choice of a library for a product feature should account for the fact that the person who understands the iOS behaviour best is the person asking for help finding it.

The sixth is the version line you would actually install. The latest published tags are v5.0.0 betas, and the recommended line is v4. A package whose newest tags are betas for a discontinued rewrite is a package where npm install still gives you the stable line, so the version should be pinned deliberately.

Editorial conclusion

react-native-big-calendar is worth adopting for a React Native app that needs to display events in a familiar week or month grid and nothing more, because it is small, it is written in TypeScript with typed props and accessibility props throughout, and it lets you replace the event cell and the header with your own components. It is the wrong choice if you need drag-and-drop or gesture-driven reordering, because the project has discontinued its own v5 experiment in that direction and points at a separate library instead. Before you adopt it, check the three things the project states about itself: that v4 is the stable, actively maintained release line and that the v5 code on the v5 branch is preserved for reference only; that the peer dependencies are react and react-native plus react-native-web if you are on the Web, with @types/react and @types/react-native needed for TypeScript; and that the library is read-mostly, since the v5 swipe rewrite that would have brought gesture-driven rescheduling is exactly the work that was dropped.

Frequently asked questions

Official sources

1. acro5piano/react-native-big-calendar on GitHub
2. License: MIT
3. Project website
4. README
5. Releases