A modern, customizable React calendar component library with Material-UI
npm install react-calendar-agendaA modern, customizable React calendar component library built with Material-UI and TypeScript.
!npm version
!npm downloads
!License
!TypeScript
- ๐จ 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
``bash`
npm install react-calendar-agenda
This library requires the following peer dependencies:
`bash`
npm install @mui/material @mui/icons-material @emotion/react @emotion/styled
`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 (
onEventAdd={handleEventAdd}
onEventEdit={handleEventEdit}
onEventDelete={handleEventDelete}
dialog={
/>
);
}
export default App;
`
> ๐ Para uso detalhado, consulte o Guia Completo de Uso
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.
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
}
Date range structure:
`tsx`
interface DateRange {
startDate: string; // Start date (YYYY-MM-DD format)
endDate: string; // End date (YYYY-MM-DD format)
}
The calendar supports three main views that can be switched dynamically:
`tsx
import { createTheme } from '@mui/material/styles';
const customTheme = createTheme({
palette: {
primary: {
main: '#1976d2',
},
secondary: {
main: '#dc004e',
},
},
components: {
MuiCalendar: {
styleOverrides: {
root: {
// Custom calendar styles
},
},
},
},
});
`
`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
}
];
`tsx
import { Button } from '@mui/material';
const CustomCalendar = () => {
const headerActions = (
);
return (
headerActions={headerActions}
dialog={
/>
);
};
`
`tsx
import { Dialog, DialogContent } from '@mui/material';
const CustomEventDialog = ({ open, onClose, event, isEditing }) => {
return (
);
};
const MyCalendar = () => {
return (
dialog={
/>
);
};
`
`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 (
onEventAdd={handleEventAdd}
dialog={
/>
);
};
`
- Node.js 16+
- npm 8+
`bashClone the repository
git clone https://github.com/calendar-dev/react-material-calendar.git
cd react-material-calendar
$3
`bash
Run Jest tests
npm testRun Cypress component tests
npm run test:cypressRun 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`)This project is licensed under the MIT License - see the LICENSE file for details.
- ๐ Documentation
- ๐ Report Bug
- ๐ก Request Feature