React Boxed Calendar

A highly customizable, flexible React calendar component with single and range date selection modes, built with TypeScript and Tailwind CSS.

Features

• 📅 Single date and date range selection modes
• 🎨 Fully customizable theme using Tailwind CSS classes
• 🔒 Disable past/future dates, weekends, or custom dates
• 🌍 Locale support for weekdays and month names
• 📱 Responsive sizes (sm, md, lg)
• ♿ Accessibility-friendly
• 💪 Written in TypeScript with full type support
• 🎯 Zero external dependencies (except React and Tailwind CSS)

Installation

npm install react-boxed-calendar

Make sure you have Tailwind CSS configured in your project. If not, follow the Tailwind CSS installation guide.

Usage

Basic Example (Single Date Selection)

import { useState } from "react";
import { Calendar } from "react-boxed-calendar";

function App() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(null);

  return (
    <Calendar
      mode="single"
      selectedDate={selectedDate}
      onDateChange={setSelectedDate}
    />
  );
}

Date Range Selection

import { useState } from "react";
import { Calendar } from "react-boxed-calendar";

function App() {
  const [range, setRange] = useState({ start: null, end: null });

  const handleRangeChange = (start: Date | null, end: Date | null) => {
    setRange({ start, end });
  };

  return (
    <Calendar
      mode="range"
      selectedRange={range}
      onRangeChange={handleRangeChange}
    />
  );
}

Advanced Configuration

<Calendar
  mode="single"
  selectedDate={selectedDate}
  onDateChange={setSelectedDate}
  disablePastDates={true}
  disableWeekends={true}
  highlightToday={true}
  weekStartsOn={1} // Monday
  size="lg"
  theme={{
    selectedBg: "bg-purple-600",
    selectedText: "text-white",
    todayBg: "bg-purple-100",
    todayText: "text-purple-600",
    normalText: "text-gray-700",
    normalHoverBg: "hover:bg-gray-200",
    disabledBg: "bg-gray-100",
    disabledText: "text-gray-400",
    borderRadius: "rounded-xl",
  }}
  locale={{
    weekDays: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
    monthNames: [
      "January",
      "February",
      "March",
      "April",
      "May",
      "June",
      "July",
      "August",
      "September",
      "October",
      "November",
      "December",
    ],
  }}
/>

Props

Prop	Type	Default	Description
mode	"single" | "range"	"single"	Selection mode
selectedDate	Date | null	null	Currently selected date (single mode)
onDateChange	(date: Date) => void	-	Callback when date is selected (single mode)
selectedRange	{ start: Date | null; end: Date | null }	{ start: null, end: null }	Selected date range (range mode)
onRangeChange	(start: Date | null, end: Date | null) => void	-	Callback when range is selected (range mode)
minDate	Date	-	Minimum selectable date
maxDate	Date	-	Maximum selectable date
disablePastDates	boolean	false	Disable all past dates
disableFutureDates	boolean	false	Disable all future dates
disableWeekends	boolean	false	Disable weekends (Sat & Sun)
disableMonthNav	boolean	false	Disable month navigation
isDateDisabled	(date: Date) => boolean	-	Custom function to disable specific dates
highlightToday	boolean	true	Highlight today's date
weekStartsOn	0 | 1	0	Week start day (0=Sunday, 1=Monday)
locale	object	-	Custom locale for weekdays and month names
theme	object	-	Custom theme configuration
size	"sm" | "md" | "lg"	"md"	Calendar size

Theme Customization

The theme prop accepts an object with the following Tailwind CSS class strings:

{
  selectedBg?: string;        // Background for selected dates
  selectedText?: string;      // Text color for selected dates
  todayBg?: string;          // Background for today
  todayText?: string;        // Text color for today
  normalText?: string;       // Text color for normal dates
  normalHoverBg?: string;    // Hover background for normal dates
  disabledBg?: string;       // Background for disabled dates
  disabledText?: string;     // Text color for disabled dates
  borderRadius?: string;     // Border radius for date cells
}

Custom Date Disabling

You can disable specific dates using the isDateDisabled callback:

<Calendar
  isDateDisabled={(date) => {
    // Disable specific dates (e.g., holidays)
    const holidays = [
      new Date(2024, 11, 25), // Christmas
      new Date(2024, 0, 1), // New Year
    ];
    return holidays.some(
      (holiday) => holiday.toDateString() === date.toDateString()
    );
  }}
/>

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Follow CONTRIBUTING.md for guidelines.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.