Calendar

A full‑featured calendar component built with react‑big‑calendar. It can display events in month, week, day, or agenda views and includes navigation and view‑switching capabilities, making it suitable for any site that needs scheduling, event management, or date visualization.

Use Cases

• Event calendars (conferences, meetups, community events, public calendars)
• Appointment booking (service providers, consultants, salons, medical offices)
• Class/course schedules (educational institutions, training programs, workshops)
• Availability displays (showing when services/resources are available)
• Team calendars (project deadlines, team meetings, shared schedules)
• Shift planning (employee schedules, on‑call rotations, staffing calendars)
• Content calendars (blog post schedules, social media planning, publication dates)
• Reservation systems (room bookings, equipment rentals, facility scheduling)
• Project timelines (milestone tracking, sprint planning, delivery schedules)
• Personal calendars (task tracking, habit tracking, life planning)

Properties

events

Array of calendar events. Each event must have title, start, and end properties. Type: array. Required: true.

Tip: Provide 3‑5 sample events, spread them across different days/weeks, use realistic durations (e.g., 1 hour for meetings, full day for events), give specific titles such as “Q4 Planning Meeting”, and add descriptions for context.

defaultView

Initial calendar view when page loads. Users can switch views using toolbar. Type: string. Options: month, week, day, agenda. Default: month.

Visual Impact: month – full month grid showing all days; week – 7‑day view with time slots; day – single day with time slots; agenda – list view showing upcoming events chronologically.

Tip: Use month for most calendars, week for appointment booking, month for event calendars, day for packed schedules, agenda for simple event listings.

title

Optional calendar title displayed above the calendar. Explains what events the calendar shows. Type: string. Not required.

Tip: Use the title to explain purpose (e.g., “Yoga Class Schedule”), be specific about time period or category, and keep it under 50 characters for a clean display.

height

Calendar height in pixels. Width is always 100 % (responsive). Type: number. Default: 600.

Tip: 600 px works well for month view, 700‑800 px for week view, 800 px for day view, 500‑600 px for agenda view, and avoid heights over 800 px on mobile.

showToolbar

Show calendar toolbar with navigation (prev/next), view switcher (month/week/day/agenda), and date display. Type: boolean. Default: true.

Visual Impact: true – toolbar appears at top with navigation arrows, current date/range, and view buttons; false – no toolbar, calendar is static.

Tip: ALWAYS set to true for functional calendars; use false only for static previews where interaction isn’t needed.

onSlotClick

JavaScript code executed when user clicks on an empty calendar slot (date/time without event). Use for booking, creating appointments, or scheduling new events. Type: string. Not required.

Tip: Navigate to a booking/creation form with date parameters in the URL, use context.slot.start.toISOString() for clean date format, provide visual feedback or navigation, and leave empty for read‑only calendars.

onEventClick

JavaScript code executed when user clicks on an existing calendar event. Use for viewing event details, editing events, or event management. Type: string. Not required.

Tip: Navigate to a detail page with event info in URL parameters, encode text values with encodeURIComponent(), pass event IDs if available, and leave empty for display‑only calendars.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Applies to outermost Section container. Type: string. Not required.

Best Practices

• Use month view as default – most familiar to users, good overview
• Use week view for detailed scheduling with time slots (appointments, shifts)
• Use day view for hour‑by‑hour schedules (busy calendars with many events)
• Use agenda view for list‑based event browsing (upcoming events, chronological view)
• Always set showToolbar: true – users need navigation and view switching
• Set appropriate height: 600px for month view, 700‑800px for week/day views
• Use clear event titles – users should understand what event is at a glance
• Include start AND end times – calendar needs both for proper rendering
• Use ISO date format for dates: 'YYYY-MM-DD HH:mm' (e.g., '2025-01-15 10:00')
• Provide realistic sample events – 3‑5 events spread across different days
• Add optional descriptions for event details
• Consider time zones if events span multiple locations
• Add context above calendar explaining what it shows (Heading + Text)

Common Mistakes

Using wrong date format for start/end

Why it's a problem: Calendar expects 'YYYY-MM-DD HH:mm' but receives '1/15/2025' or timestamps – calendar breaks.

Fix: Always use ISO‑like format: '2025-01-15 10:00' for start/end dates.

Not providing end time for events

Why it's a problem: Calendar requires both start AND end to render events properly. Missing end = broken display.

Fix: Every event must have start and end. For all‑day events: start '09:00', end '17:00'.

Setting showToolbar: false on functional calendars

Why it's a problem: Users can’t navigate to different dates or switch views. Calendar is stuck on initial view.

Fix: ALWAYS use showToolbar: true unless calendar is purely decorative preview.

Only providing 1-2 sample events

Why it's a problem: Calendar looks empty and doesn’t demonstrate functionality well.

Fix: Provide 3‑5 realistic sample events spread across different days.

Setting height too small for chosen view

Why it's a problem: 400px month view = compressed calendar, illegible dates. 500px week view = can’t see time slots.

Fix: Month: 600px, Week: 700‑800px, Day: 800px, Agenda: 500‑600px.

Vague event titles like 'Event 1', 'Meeting', 'Appointment'

Why it's a problem: Users don’t know what events are. Defeats purpose of calendar.

Fix: Use specific titles: 'Q4 Planning Meeting', 'Dental Checkup', 'Yoga Class - Beginner'.

Not adding context around calendar

Why it's a problem: Users don’t know what calendar shows. Is it team schedule? Available slots? Events?

Fix: Add Heading + Text above calendar explaining what it shows and how to use it.