calendar-react/USAGE_GUIDE.md

Calendar Component Usage Guide

✏️ Header Text Transform (v1.2.0+)

Customize how day names are displayed with a transform function:

import { Month } from 'react-calendario';

// Example 1: Two-letter abbreviations
<Month
  date={new Date()}
  headerStyle="compacted"  // Shows "MON", "TUE", etc.
  headerTextTransform={(dayName) => dayName.slice(0, 2)}  // Returns "MO", "TU", etc.
/>

// Example 2: Custom mapping
const customDayNames = (dayName: string) => {
  const map: Record<string, string> = {
    'MON': 'Mo', 'TUE': 'Tu', 'WED': 'We',
    'THU': 'Th', 'FRI': 'Fr', 'SAT': 'Sa', 'SUN': 'Su'
  };
  return map[dayName] || dayName;
};

<Month
  date={new Date()}
  headerStyle="compacted"
  headerTextTransform={customDayNames}
/>

// Example 3: Lowercase
<Month
  date={new Date()}
  headerStyle="tiny"
  headerTextTransform={(dayName) => dayName.toLowerCase()}
/>

The headerTextTransform function:

• Receives the day name after headerStyle processing
• Can return any string for display
• Works with all components: Year, Month, Week, DateRange, Day

🎨 Custom Color Schemes

Basic Active Colors (Simple)

For highlighting specific dates with custom colors:

import { Year, ActiveColors } from 'react-calendario';

const activeColors: ActiveColors = {
  headerBg: '#D4EDDA',
  headerColor: '#155724',
  contentBg: '#28A745',
  contentColor: '#FFFFFF'
};

<Year 
  year={2025}
  activeDates={[new Date(2025, 0, 1), new Date(2025, 11, 25)]}
  activeColors={activeColors}
/>

Comprehensive Color Scheme (Advanced)

Full control over colors for every state and day type:

import { Year, ColorScheme } from 'react-calendario';

const colorScheme: ColorScheme = [
  // Today's date colors for different states
  { 
    weekSplit: 'weekday', 
    relative: 'today',
    state: 'default',  // Today when it's a normal weekday
    colors: { 
      header: { backgroundColor: '#ffd700', color: '#000000' },
      content: { backgroundColor: '#fff9e6', color: '#000000' }
    }
  },
  { 
    weekSplit: 'weekday', 
    relative: 'today',
    state: 'active',  // Today when it's active/clicked
    colors: { 
      header: { backgroundColor: '#ffed4e', color: '#000000' },
      content: { backgroundColor: '#fff59d', color: '#000000' }
    }
  },
  { 
    weekSplit: 'weekday', 
    relative: 'today',
    state: 'rangeStart',  // Today when it starts a range
    colors: { 
      header: { backgroundColor: '#ffc107', color: '#000000' },
      content: { backgroundColor: '#ffeb3b', color: '#000000' }
    }
  },
  // Regular weekday colors (anyday is default when relative is omitted)
  { 
    weekSplit: 'weekday', 
    state: 'default',  // Normal weekday
    colors: { 
      header: { backgroundColor: '#2c3e50', color: '#ffffff' },
      content: { backgroundColor: '#ffffff', color: '#2c3e50' }
    }
  },
  { 
    weekSplit: 'weekday', 
    state: 'rangeStart',  // First day of selected range
    colors: {
      header: { backgroundColor: '#2980b9', color: '#ffffff' },
      content: { backgroundColor: '#3498db', color: '#ffffff' }
    }
  },
  { 
    weekSplit: 'weekday', 
    state: 'rangeMid',  // Middle days of selected range
    colors: {
      header: { backgroundColor: '#5dade2', color: '#ffffff' },
      content: { backgroundColor: '#aed6f1', color: '#1a5490' }
    }
  },
  
  // Weekend colors
  { 
    weekSplit: 'weekend', 
    state: 'default',  // Normal weekend
    colors: {
      header: { backgroundColor: '#7f8c8d', color: '#ffffff' },
      content: { backgroundColor: '#ecf0f1', color: '#34495e' }
    }
  },
  { 
    weekSplit: 'weekend', 
    state: 'rangeStart',  // Weekend that starts a range
    colors: {
      header: { backgroundColor: '#2980b9', color: '#ffffff' },
      content: { backgroundColor: '#3498db', color: '#ffffff' }
    }
  },
  // ... more states
];

<Year 
  year={2025}
  colorScheme={colorScheme}
/>

Color Scheme Dimensions:

Week Split (weekSplit):

• weekday - Monday through Friday
• weekend - Saturday and Sunday (or custom weekend days)

Relative (relative, optional):

• today - Today's date (automatically detected)
• anyday - Any other date (default when omitted)

State (state):

• default - Normal day appearance
• selecting - Day is being hovered during selection
• rangeStart - First day of a range
• rangeEnd - Last day of a range
• rangeMid - Middle days of a selected range
• active - Special highlighted days (holidays, events)

Backwards Compatibility:

• type is still supported but deprecated (use weekSplit instead)

🌍 Locale Support

Basic Usage

import { Year } from 'react-calendario';
import { fr, de, ja, es } from 'date-fns/locale';

// French
<Year year={2025} locale={fr} />

// German
<Year year={2025} locale={de} />

// Japanese
<Year year={2025} locale={ja} />

// Spanish
<Year year={2025} locale={es} />

What Gets Localized:

• Month names (January → Janvier → Januar → 一月)
• Day headers based on style:
  • expanded: Full names (MONDAY → LUNDI → MONTAG)
  • compacted: 3-letter (MON → LUN → MO)
  • tiny: Single letter (M → L → M)
• Date formats in tooltips and labels

Available Locales:

All date-fns locales are supported. Common ones include:

• enUS - English (US) - Default
• es - Spanish
• fr - French
• de - German
• it - Italian
• pt - Portuguese
• ja - Japanese
• ko - Korean
• zhCN - Chinese (Simplified)
• ru - Russian
• ar - Arabic
• nl - Dutch
• pl - Polish
• tr - Turkish
• sv - Swedish
• nb - Norwegian

🎯 Combined Example

Using both features together:

import { Year, ColorScheme } from 'react-calendario';
import { fr } from 'date-fns/locale';

const frenchHolidayScheme: ColorScheme = [
  // Regular days with French aesthetic
  { 
    type: 'weekday', 
    state: 'default',
    colors: { 
      header: { backgroundColor: '#002395', color: '#ffffff' },  // French blue
      content: { backgroundColor: '#ffffff', color: '#002395' }
    }
  },
  // Weekends in subtle gray
  { 
    type: 'weekend', 
    state: 'default',
    colors: {
      header: { backgroundColor: '#95a5a6', color: '#ffffff' },
      content: { backgroundColor: '#ecf0f1', color: '#34495e' }
    }
  },
  // French holidays in red
  { 
    type: 'weekday', 
    state: 'active',
    colors: {
      header: { backgroundColor: '#ed2939', color: '#ffffff' },  // French red
      content: { backgroundColor: '#c0392b', color: '#ffffff' }
    }
  },
  { 
    type: 'weekend', 
    state: 'active',
    colors: {
      header: { backgroundColor: '#c0392b', color: '#ffffff' },
      content: { backgroundColor: '#ed2939', color: '#ffffff' }
    }
  }
];

const frenchHolidays = [
  new Date(2025, 0, 1),   // Jour de l'An
  new Date(2025, 4, 1),   // Fête du Travail
  new Date(2025, 6, 14),  // Fête Nationale
  new Date(2025, 11, 25)  // Noël
];

<Year 
  year={2025}
  locale={fr}
  colorScheme={frenchHolidayScheme}
  activeDates={frenchHolidays}
  dayHeaderStyle="compacted"
/>

📝 Tips

1. Color Scheme Fallbacks: You don't need to define every state. The system intelligently falls back:

   • Weekend states → Weekday states of same type
   • Missing states → Default state
   • Weekend default → Weekday default

2. Performance: ColorScheme is more efficient than inline styles for large calendars

3. Accessibility: Ensure sufficient color contrast between background and text colors

4. Locale + Colors: Combine locale with themed colors for culturally appropriate calendars

5. Weekend Customization: Weekend days are automatically detected and styled differently, including when they're part of a selected range