React Material Calendar

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

!npm version
!npm downloads
!License
!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

``bash
npm install react-calendar-agenda
`

$3

This library requires the following peer dependencies:

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

Quick Start

`tsx
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([
{
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 => {
setEvents(prev => [...prev, event]);
console.log('New event created:', event);
return true;
};

const handleEventEdit = async (event: CalendarEvent, previousEvent?: CalendarEvent): Promise => {
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 (

events={events}
onEventAdd={handleEventAdd}
onEventEdit={handleEventEdit}
onEventDelete={handleEventDelete}
dialog={} // REQUIRED for interactions
/>

);
}

export default App;
`

> 📖 Para uso detalhado, consulte o Guia Completo de Uso

API Reference

$3

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 | No | Callback when adding a new event |
| onEventEdit | (event: CalendarEvent, previousEvent?: CalendarEvent) => Promise | 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.

$3

Event data structure:

`tsx
interface CalendarEvent> {
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
}
`

$3

Date range structure:

`tsx
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:

$3

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

$3

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

$3

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

Customization

$3

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

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

$3

`tsx
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

$3

- 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

$3

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

$3

- 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

$3

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

const CustomCalendar = () => {
const headerActions = (

Quick Add Event

);

return (
events={events}
headerActions={headerActions}
dialog={} // REQUIRED for interactions
/>
);
};
`

$3

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

const CustomEventDialog = ({ open, onClose, event, isEditing }) => {
return (




{/ Your custom event form /}



);
};

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

$3

`tsx
const ApiCalendar = () => {
const handleEventAdd = async (event: CalendarEvent): Promise => {
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 (
events={events}
onEventAdd={handleEventAdd}
dialog={} // REQUIRED for interactions
/>
);
};
`

Development

$3

- Node.js 16+
- npm 8+

$3

`bash


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
`

$3

`bash


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

$3

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