Newpaper Calendar

A highly-customisable, feature-rich calendar component for React Native and Expo.
It supports month / week / day views, full CRUD event management, theming, and hybrid (controlled / uncontrolled) state management – making it perfect for everything from quick prototypes to production scheduling apps.

Features

• ✅ Three views – month, week and day
• ✅ Event CRUD – create, edit, delete with colour coding
• ✅ Hybrid state – library can manage its own state or be 100 % controlled by the parent
• ✅ Fully themable – override any colour, font, spacing or radius value
• ✅ Configurable icons – uses Expo Ionicons by default, but any React component works
• ✅ Accessible & keyboard-friendly
• ✅ Type-safe – written in TypeScript with full declaration files
• ✅ No native code – pure JS, runs on iOS, Android and Web

Installation

# with npm
npm install newpaper-calendar date-fns
# or with yarn / pnpm
yarn add newpaper-calendar date-fns

Peer dependencies

| Package | Version (or higher) | |----------|---------------------| | react | 16.8.0 | | react-native | 0.60.0 | | date-fns | 2.0.0 |

Expo projects already include compatible versions of React and React Native.
Because icons default to Ionicons, ensure you have them (Expo SDK already does):

expo install @expo/vector-icons

Quick Start (Uncontrolled Mode)

import React from 'react';
import { Calendar } from 'newpaper-calendar';

export default function App() {
  return (
    <Calendar
      /* just pass events to start */
      defaultEvents={[
        {
          id: '1',
          title: 'Kick-off',
          date: '2025-06-01',
          time: '09:00',
          color: '#5E60CE',
        },
      ]}
    />
  );
}

In uncontrolled mode the library keeps its own state.
Use callbacks such as onEventsChange or onDateSelect to stay in sync.

Controlled Mode

import React, { useState } from 'react';
import { Calendar, CalendarEvent } from 'newpaper-calendar';

export default function ControlledDemo() {
  const [selectedDate, setSelectedDate] = useState(new Date());
  const [events, setEvents] = useState<CalendarEvent[]>([]);

  return (
    <Calendar
      /* 100 % controlled */
      selectedDate={selectedDate}
      events={events}
      view="week"
      onDateSelect={setSelectedDate}
      onEventsChange={setEvents}
      onEventCreate={(date) => console.log('Create new on', date)}
    />
  );
}

Advanced Configuration

Theming

Override any part of the default theme:

import { Calendar, defaultTheme } from 'newpaper-calendar';

const myTheme = {
  ...defaultTheme,
  primary: '#6366F1',
  background: '#F9FAFB',
  text: '#111827',
  eventColors: ['#22D3EE', '#F87171', '#A78BFA'],
};

<Calendar theme={myTheme} />;

Custom Icons

Pass an object whose keys match the icon slots.
Any React component (SVG, PNG, FontIcon, etc.) is accepted.

import { MaterialIcons } from '@expo/vector-icons';

const icons = {
  chevronLeft: (p) => <MaterialIcons name="chevron-left" {...p} />,
  chevronRight: (p) => <MaterialIcons name="chevron-right" {...p} />,
  plus: (p) => <MaterialIcons name="add" {...p} />,
};

<Calendar icons={icons} />;

Disabling Internal Modals

Use the event callbacks exclusively and set feature flags:

<Calendar
  enableEventCreation={false}
  enableEventEditing={false}
  onEventPress={(e) => navigation.navigate('EventDetails', { e })}
/>

API Reference

<Calendar /> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | events | CalendarEvent[] | – | Controlled events array | | defaultEvents | CalendarEvent[] | [] | Uncontrolled starting events | | selectedDate | Date | – | Controlled selected date | | defaultSelectedDate | Date | new Date() | Uncontrolled starting date | | view | 'month'\|'week'\|'day' | – | Controlled view | | defaultView | Same as above | 'month' | Uncontrolled view | | settings | Partial<CalendarSettings> | – | Controlled settings | | defaultSettings | Partial<CalendarSettings> | – | Uncontrolled settings | | theme | Partial<CalendarTheme> | – | Theme overrides | | icons | Partial<CalendarIcons> | Ionicons defaults | Custom icon set | | enableEventCreation | boolean | true | | enableEventEditing | boolean | true | | enableSettings | boolean | true | | showHeader | boolean | true | | showNavigation | boolean | true | | — Callbacks — | | onDateSelect(date) | (Date) => void | – | | onEventsChange(events) | (CalendarEvent[]) => void | – | | onViewChange(view) | (CalendarView) => void | – | | onEventPress(event) | (CalendarEvent) => void | – | | onEventCreate(date) | (Date) => void | – | | onEventEdit(event) | (CalendarEvent) => void | – | | onEventDelete(id) | (string) => void | – | | onSettingsChange(settings) | (CalendarSettings) => void | – |

CalendarEvent

interface CalendarEvent {
  id: string;
  title: string;
  description?: string;
  date: 'YYYY-MM-DD';
  time: 'HH:MM';
  endTime?: 'HH:MM';
  location?: string;
  color?: string; // hex
  isAllDay?: boolean;
}

CalendarTheme

See defaultTheme exported from the package for the full structure.

Utility Helpers

All date-helper functions are re-exported:

import { formatToISODate, getWeekNumber } from 'newpaper-calendar';

TypeScript

The package ships with .d.ts files – IDEs get full IntelliSense.

Example App

An Expo example is located in /library/example.
Run it locally:

cd library/example
yarn && expo start

Contributing

PRs & issues are welcome!
Please open an issue first if you plan major changes.

git clone https://github.com/yourname/react-native-calendar-pro
cd react-native-calendar-pro
yarn
yarn example # run demo

License

MIT © Aloy Sathekge