React Material Calendar

A modern, customizable React calendar component library built with Material-UI and TypeScript.

Features

• 🎨 Material-UI Integration - Beautiful, consistent design with Material-UI components
• 📱 Responsive - Works perfectly on desktop, tablet, and mobile devices
• 🎯 Multiple Views - Month, Week, and Day view support
• ⚡ TypeScript - Full TypeScript support with comprehensive type definitions
• 🎛️ Customizable - Highly customizable themes and styling
• 📅 Event Management - Built-in event creation, editing, and management
• 🕐 Time Selection - Interactive time selection with conflict detection
• 🧪 Well Tested - Comprehensive test suite with Jest and Cypress
• 📚 Storybook - Interactive documentation and component playground

Installation

npm install react-calendar-agenda

Peer Dependencies

This library requires the following peer dependencies:

npm install @mui/material @mui/icons-material @emotion/react @emotion/styled

Quick Start

import React, { useState } from 'react';
import { Calendar } from './Calendar';
import { CalendarEvent } from './types';
import { EventDialog } from './EventDialog'; // Required for interactions
import { ThemeProvider, createTheme } from '@mui/material/styles';

const theme = createTheme();

function App() {
  const [events, setEvents] = useState<CalendarEvent[]>([
    {
      id: '1',
      title: 'Meeting with Team',
      description: 'Weekly team standup',
      startTime: '10:00',
      endTime: '11:00',
      date: '2024-01-15',
      color: '#1976d2'
    },
    {
      id: '2',
      title: 'Project Review',
      description: 'Quarterly project review',
      startTime: '14:30',
      endTime: '15:30',
      date: '2024-01-16',
      color: '#4caf50'
    }
  ]);

  const handleEventAdd = async (event: CalendarEvent): Promise<boolean> => {
    setEvents(prev => [...prev, event]);
    console.log('New event created:', event);
    return true;
  };

  const handleEventEdit = async (event: CalendarEvent, previousEvent?: CalendarEvent): Promise<boolean> => {
    setEvents(prev => prev.map(e => e.id === event.id ? event : e));
    console.log('Event updated:', { previous: previousEvent, current: event });
    return true;
  };

  const handleEventDelete = (eventId: string) => {
    setEvents(prev => prev.filter(e => e.id !== eventId));
    console.log('Event deleted:', eventId);
  };

  return (
    <ThemeProvider theme={theme}>
      <Calendar
        events={events}
        onEventAdd={handleEventAdd}
        onEventEdit={handleEventEdit}
        onEventDelete={handleEventDelete}
        dialog={<EventDialog />} // REQUIRED for interactions
      />
    </ThemeProvider>
  );
}

export default App;

📖 Para uso detalhado, consulte o Guia Completo de Uso

API Reference

Calendar

The main calendar component that renders the calendar interface with integrated event management.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | events | CalendarEvent[] | No | Array of calendar events (default: []) | | isLoading | boolean | No | Loading state indicator (default: false) | | onEventAdd | (event: CalendarEvent) => Promise<boolean> | No | Callback when adding a new event | | onEventEdit | (event: CalendarEvent, previousEvent?: CalendarEvent) => Promise<boolean> | No | Callback when editing an event | | onEventDelete | (eventId: string) => void | No | Callback when deleting an event | | onDateRangeChange | (range: DateRange) => void | No | Callback when date range changes | | headerActions | ReactNode | No | Custom actions in the calendar header | | dialog | ReactNode | Yes (for interactions) | REQUIRED dialog component for event management |

⚠️ Critical: The dialog prop is MANDATORY when using interactive features. Without it, users cannot create, edit, or delete events through the UI.

CalendarEvent

Event data structure:

interface CalendarEvent<TCustomData = Record<string, unknown>> {
  id: string;                    // Unique event identifier
  title: string;                 // Event title
  description: string;           // Event description
  startTime: string;            // Start time (HH:MM format)
  endTime: string;              // End time (HH:MM format)
  date: string;                 // Event date (YYYY-MM-DD format)
  color?: string;               // Event color (hex format)
  customData?: TCustomData;     // Custom data for extensibility
}

DateRange

Date range structure:

interface DateRange {
  startDate: string;  // Start date (YYYY-MM-DD format)
  endDate: string;    // End date (YYYY-MM-DD format)
}

Views

The calendar supports three main views that can be switched dynamically:

Month View

• Grid layout showing the entire month
• Event indicators on calendar cells
• Click to navigate to day/week view
• Compact event display

Week View

• Detailed week layout with hourly slots
• Event cards positioned by time
• Scrollable timeline
• Time selection for creating events

Day View

• Single day detailed view
• Hourly time slots
• Detailed event information
• Precise time selection and event management

Customization

Theme Customization

import { createTheme } from '@mui/material/styles';

const customTheme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
    secondary: {
      main: '#dc004e',
    },
  },
  components: {
    MuiCalendar: {
      styleOverrides: {
        root: {
          // Custom calendar styles
        },
      },
    },
  },
});

Event Colors

const events = [
  {
    id: '1',
    title: 'Important Meeting',
    start: new Date(),
    end: new Date(),
    color: '#f44336', // Red for important events
  },
  {
    id: '2',
    title: 'Team Standup',
    start: new Date(),
    end: new Date(),
    color: '#4caf50', // Green for regular meetings
  }
];

Interactive Features

Creating Events

• Click on empty cell: Opens dialog with time pre-filled
• Drag to select time: Creates event with selected time range
• Automatic validation: Ensures valid time ranges and required fields

Editing Events

• Click on existing event: Opens dialog with event data pre-filled
• Real-time updates: Changes are reflected immediately
• Conflict detection: Warns about overlapping events

Event Management

• Color coding: 8 preset colors for easy categorization
• Time selection: 30-minute intervals for precise scheduling
• Form validation: Built-in validation for all fields
• Loading states: Visual feedback during async operations

Advanced Usage

Custom Header Actions

import { Button } from '@mui/material';

const CustomCalendar = () => {
  const headerActions = (
    <Button variant="contained" onClick={handleAddEvent}>
      Quick Add Event
    </Button>
  );

  return (
    <Calendar
      events={events}
      headerActions={headerActions}
      dialog={<EventDialog />} // REQUIRED for interactions
    />
  );
};

Custom Dialog

import { Dialog, DialogContent } from '@mui/material';

const CustomEventDialog = ({ open, onClose, event, isEditing }) => {
  return (
    <Dialog open={open} onClose={onClose} maxWidth="md" fullWidth>
      <DialogContent>
        {/* Your custom event form */}
      </DialogContent>
    </Dialog>
  );
};

const MyCalendar = () => {
  return (
    <Calendar
      events={events}
      dialog={<CustomEventDialog />} // REQUIRED for interactions
    />
  );
};

API Integration

const ApiCalendar = () => {
  const handleEventAdd = async (event: CalendarEvent): Promise<boolean> => {
    try {
      const response = await fetch('/api/events', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(event)
      });
      
      if (response.ok) {
        const newEvent = await response.json();
        setEvents(prev => [...prev, newEvent]);
        return true;
      }
      
      return false;
    } catch (error) {
      console.error('Error creating event:', error);
      return false;
    }
  };

  return (
    <Calendar
      events={events}
      onEventAdd={handleEventAdd}
      dialog={<EventDialog />} // REQUIRED for interactions
    />
  );
};

Development

Prerequisites

• Node.js 16+
• npm 8+

Setup

# Clone the repository
git clone https://github.com/calendar-dev/react-material-calendar.git
cd react-material-calendar

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Run Storybook
npm run storybook

Testing

# Run Jest tests
npm test

# Run Cypress component tests
npm run test:cypress

# Run all tests with coverage
npm run test:coverage

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Report Bug
• 💡 Request Feature

Changelog

v1.0.0

• Initial release
• Month, Week, and Day views
• Event management
• Material-UI integration
• TypeScript support
• Comprehensive testing suite