react-native-mat-calendar

A feature-rich, Material Design 3 calendar component for React Native with multiple view modes, event management, and extensive customization options.

⚠️ Production Notice: This library is currently used in production and is tailored to the maintainer's specific use case. While it's stable and functional, contributions, bug reports, and feature requests are always welcome and appreciated! Please feel free to open an issue or submit a pull request.

Compatibility

This package is written in plain JavaScript/TypeScript and is compatible with:

• ✅ Expo - Works out of the box with Expo projects
• ✅ Bare React Native - Compatible with bare React Native projects
• ✅ Web - Supports React Native Web
• ✅ iOS - Full iOS support
• ✅ Android - Full Android support

No native code compilation required - this is a pure JavaScript/TypeScript library that works across all React Native platforms.

Features

• 📅 Multiple View Modes: Month, Week, Day, and List views
• 🎨 Material Design 3: Built with react-native-paper for consistent Material Design theming
• 🌍 Internationalization: Full locale support with customizable month/day names
• 🎯 Event Management: Display and manage calendar events with custom renderers
• 🎨 Customizable: Extensive props for customizing appearance and behavior
• ♿ Accessibility: Support for disabled dates and time slots
• 💾 Persistent State: View mode preference saved using AsyncStorage
• ⏰ Time Indicators: Current time line indicator in day/week views
• 📱 TypeScript: Fully typed with TypeScript support

Installation

npm install react-native-mat-calendar
# or
yarn add react-native-mat-calendar

Peer Dependencies

This library requires the following peer dependencies:

npm install react-native-paper @react-native-async-storage/async-storage
# or
yarn add react-native-paper @react-native-async-storage/async-storage

Note: Make sure you have react-native-paper properly set up in your project. See the react-native-paper documentation for setup instructions.

Usage

Basic Example

import React from 'react';
import { View } from 'react-native';
import { FullCalendar, CalendarEvent } from 'react-native-mat-calendar';
import { Provider as PaperProvider } from 'react-native-paper';

const events: CalendarEvent[] = [
  {
    id: '1',
    date: '20241215', // YYYYMMDD format
    startTime: '10:00',
    endTime: '11:30',
    color: '#FF5722',
    data: { title: 'Meeting', description: 'Team sync' },
  },
  {
    id: '2',
    date: '20241215',
    startTime: '14:00',
    endTime: '15:00',
    color: '#2196F3',
    data: { title: 'Lunch', description: 'With client' },
  },
];

export default function App() {
  return (
    <PaperProvider>
      <View style={{ flex: 1 }}>
        <FullCalendar
          events={events}
          viewMode="month"
          onEventPress={(event) => {
            console.log('Event pressed:', event);
          }}
          onDateSelect={(date) => {
            console.log('Date selected:', date);
          }}
        />
      </View>
    </PaperProvider>
  );
}

Advanced Example with Custom Renderers

import React from 'react';
import { View } from 'react-native';
import { FullCalendar, CalendarEvent } from 'react-native-mat-calendar';
import { Card, Text } from 'react-native-paper';
import { Provider as PaperProvider } from 'react-native-paper';

const events: CalendarEvent[] = [
  {
    id: '1',
    date: '20241215',
    startTime: '10:00',
    endTime: '11:30',
    data: { title: 'Team Meeting', location: 'Room A' },
  },
];

export default function App() {
  return (
    <PaperProvider>
      <View style={{ flex: 1 }}>
        <FullCalendar
          events={events}
          viewMode="week"
          currentDate="20241215"
          locale={{
            monthNames: ['January', 'February', 'March', 'April', 'May', 'June', 
                         'July', 'August', 'September', 'October', 'November', 'December'],
            dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
            dayNamesShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
            firstDayOfWeek: 0, // 0 = Sunday, 1 = Monday
            today: 'Today',
          }}
          renderWeekEvent={(event) => (
            <Card style={{ backgroundColor: '#2196F3', padding: 8 }}>
              <Text style={{ color: 'white', fontWeight: 'bold' }}>
                {event.data.title}
              </Text>
              <Text style={{ color: 'white', fontSize: 12 }}>
                {event.startTime} - {event.endTime}
              </Text>
            </Card>
          )}
          onEventPress={(event) => {
            console.log('Event pressed:', event);
          }}
          timeRange={{ startHour: 8, endHour: 20 }}
          todayNowColorLine="#FF0000"
        />
      </View>
    </PaperProvider>
  );
}

API Reference

FullCalendar Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | events | CalendarEvent[] \| EventsByDate | undefined | Events as array or date-keyed object | | viewMode | 'month' \| 'week' \| 'day' \| 'list' | 'month' | Current view mode | | currentDate | string | Today (YYYYMMDD) | Initial/current date in YYYYMMDD format | | selectedDate | string | undefined | Selected date in YYYYMMDD format | | onDateChange | (date: string) => void | undefined | Callback when date changes | | onDateSelect | (date: string) => void | undefined | Callback when date is selected | | onEventPress | (event: CalendarEvent) => void | undefined | Callback when event is pressed | | onViewModeChange | (viewMode: ViewMode) => void | undefined | Callback when view mode changes | | onCellPress | (data: { date: string; time?: { hour: number; minutes: number }; viewMode: ViewMode }) => void | undefined | Callback when a cell is pressed | | renderEvent | (event: CalendarEvent) => React.ReactNode | undefined | Custom event renderer (fallback for all views) | | renderMonthEvent | (event: CalendarEvent) => React.ReactNode | undefined | Custom event renderer for month view | | renderWeekEvent | (event: CalendarEvent) => React.ReactNode | undefined | Custom event renderer for week view | | renderDayEvent | (event: CalendarEvent) => React.ReactNode | undefined | Custom event renderer for day view | | renderListEvent | (event: CalendarEvent) => React.ReactNode | undefined | Custom event renderer for list view | | renderCellContent | (date: string, events: CalendarEvent[]) => React.ReactNode | undefined | Custom cell content renderer (month view) | | locale | LocaleConfig | Italian default | Locale configuration | | theme | MD3Theme | Paper theme | React Native Paper theme | | showNavigation | boolean | true | Show navigation controls | | showViewModeSwitcher | boolean | true | Show view mode switcher | | isDayDisabled | (date: string) => boolean | undefined | Function to check if a day is disabled | | isTimeDisabled | (date: string, hour: number, minutes: number) => boolean | undefined | Function to check if a time slot is disabled | | timeRange | { startHour?: number; endHour?: number } | undefined | Time range to display in week/day views | | todayNowColorLine | string | undefined | Color for current time line (e.g., '#FF0000') |

CalendarEvent

interface CalendarEvent<TData = any> {
  id: string;
  date: string; // YYYYMMDD format
  startTime: string; // HH:mm or HH:mm:ss format
  endTime: string; // HH:mm or HH:mm:ss format
  color?: string;
  data: TData; // Typed data property for custom data
}

EventsByDate

type EventsByDate<TData = any> = Record<string, CalendarEvent<TData>[]>;

The key format is YYYYMMDD (e.g., '20241215' for December 15, 2024).

Locale Configuration

interface LocaleConfig {
  monthNames?: string[];
  monthNamesShort?: string[];
  dayNames?: string[];
  dayNamesShort?: string[];
  today?: string;
  firstDayOfWeek?: number; // 0 = Sunday, 1 = Monday, etc.
}

View Modes

Month View

Displays a traditional calendar grid showing all days of the month. Events are displayed as dots or custom renderers within each day cell.

Week View

Shows a week with time slots (30-minute intervals). Events are positioned based on their start and end times, with automatic overlap handling.

Day View

Displays a single day with hourly time slots. Perfect for detailed daily scheduling.

List View

Shows events in a list format for the selected day, sorted by time.

Date Format

All dates in this library use the YYYYMMDD format (e.g., '20241215' for December 15, 2024). This compact format is used for:

• currentDate
• selectedDate
• event.date
• Date keys in EventsByDate
• Callback parameters (onDateChange, onDateSelect, etc.)

Customization

Custom Event Rendering

You can provide custom renderers for events in different views:

<FullCalendar
  events={events}
  renderMonthEvent={(event) => (
    <View style={{ backgroundColor: event.color, padding: 4 }}>
      <Text>{event.data.title}</Text>
    </View>
  )}
  renderWeekEvent={(event) => (
    <Card>
      <Card.Content>
        <Text>{event.data.title}</Text>
        <Text>{event.startTime} - {event.endTime}</Text>
      </Card.Content>
    </Card>
  )}
/>

Disabled Dates and Times

<FullCalendar
  events={events}
  isDayDisabled={(date) => {
    // Disable weekends
    const day = new Date(date.substring(0, 4), date.substring(4, 6) - 1, date.substring(6, 8)).getDay();
    return day === 0 || day === 6;
  }}
  isTimeDisabled={(date, hour, minutes) => {
    // Disable times before 9 AM
    return hour < 9;
  }}
/>

Time Range

Limit the visible time range in week and day views:

<FullCalendar
  events={events}
  viewMode="week"
  timeRange={{ startHour: 8, endHour: 18 }}
/>

Current Time Indicator

Show a line indicating the current time in day/week views:

<FullCalendar
  events={events}
  viewMode="day"
  todayNowColorLine="#FF0000" // Red line
/>

TypeScript Support

This library is fully typed with TypeScript. All types are exported:

import {
  FullCalendar,
  CalendarEvent,
  EventsByDate,
  ViewMode,
  FullCalendarProps,
} from 'react-native-mat-calendar';

You can also use generic types for typed event data:

interface MyEventData {
  title: string;
  description: string;
  location: string;
}

const events: CalendarEvent<MyEventData>[] = [
  {
    id: '1',
    date: '20241215',
    startTime: '10:00',
    endTime: '11:00',
    data: {
      title: 'Meeting',
      description: 'Team sync',
      location: 'Room A',
    },
  },
];

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library