React Calendar Library

A modern, flexible React calendar component with Persian and Gregorian calendar support, built with React Context and TypeScript.

Features

• ✅ Persian & Gregorian Calendar Support
• ✅ React Context State Management (No Zustand dependency)
• ✅ Multiple Independent Calendar Instances
• ✅ Date Range Selection
• ✅ Customizable Themes & Styling
• ✅ Accessibility Support
• ✅ TypeScript Support
• ✅ Tailwind CSS Integration

Prerequisites

Before installing this package, check if you already have these dependencies in your project:

✅ Already Available in Your Project

Your project already includes these dependencies, so you don't need to install them again:

• ✅ react@^19.1.0 - Already installed
• ✅ react-dom@^19.1.0 - Already installed
• ✅ tailwindcss@^3.4.17 - Already installed
• ✅ @heroicons/react@^2.2.0 - Already installed
• ✅ react-date-object@^2.1.9 - Already installed
• ✅ clsx@^2.1.1 - Already installed
• ✅ tailwind-merge@^3.3.1 - Already installed

ℹ️ Only Install the Package

Since your project already has all required dependencies, you only need to install the calendar package:

npm install @zip_co/react-calendar
# or with pnpm
pnpm add @zip_co/react-calendar

🔍 Check Your Dependencies

If you're unsure about your current dependencies, run:

npm list react react-dom tailwindcss @heroicons/react react-date-object clsx tailwind-merge

⚠️ If Missing Dependencies

If any dependencies are missing from your project, install them:

# Only install what's missing from your project
npm install react@^19.0.0 react-dom@^19.0.0 tailwindcss@^3.0.0 @heroicons/react@^2.2.0 react-date-object@^2.1.9 clsx@^2.1.1 tailwind-merge@^3.3.1

Next.js Setup (Your Project)

🎉 Great News!

Your Next.js project already has all the required dependencies, so you can start using the calendar immediately!

1. Install Only the Package

# Since you already have all dependencies, just install the package
pnpm add @zip_co/react-calendar
# or
npm install @zip_co/react-calendar

2. Update Tailwind Config

Add the calendar library to your Tailwind content paths:

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
    // Add the calendar library path
    './node_modules/@zip_co/react-calendar/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

3. Start Using the Calendar

// app/calendar/page.tsx
'use client';

import { Calendar } from '@zip_co/react-calendar';

export default function CalendarPage() {
  const handleDateSelect = (date: Date) => {
    console.log('Selected date:', date);
  };

  const handleRangeSelect = (range: { start: Date; end: Date }) => {
    console.log('Selected range:', range);
  };

  return (
    <div className="p-4">
      <h1 className="text-2xl font-bold mb-4">تقویم</h1>
      <Calendar
        system="persian"
        range={true}
        disablePast={true}
        disableFuture={false}
        onDateSelect={handleDateSelect}
        onRangeSelect={handleRangeSelect}
        theme="light"
        size="md"
        className="max-w-md mx-auto"
      />
    </div>
  );
}

4. Multiple Calendars

// app/multi-calendar/page.tsx
'use client';

import { MultiCalendar } from '@zip_co/react-calendar';

export default function MultiCalendarPage() {
  const calendars = [
    {
      id: "persian-calendar",
      config: {
        system: "persian",
        rangeMode: true,
        disablePast: true,
        disableFuture: false,
        weekStart: 0,
      },
      props: {
        theme: "light",
        size: "md",
        ariaLabel: "Persian Calendar",
      }
    },
    {
      id: "gregorian-calendar",
      config: {
        system: "gregorian",
        rangeMode: false,
        disablePast: false,
        disableFuture: true,
        weekStart: 1,
      },
      props: {
        theme: "dark",
        size: "md",
        ariaLabel: "Gregorian Calendar",
      }
    }
  ];

  return (
    <MultiCalendar
      calendars={calendars}
      layout="grid"
      gap={4}
    />
  );
}

5. Integration with Your Existing UI Library

Since you're using HeroUI, the calendar will work perfectly with your existing design system:

// Works great with your HeroUI components
import { Card, CardBody } from "@heroui/react";
import { Calendar } from '@zip_co/react-calendar';

export default function CalendarCard() {
  return (
    <Card className="max-w-md">
      <CardBody>
        <Calendar
          system="persian"
          range={true}
          theme="light"
          className="w-full"
        />
      </CardBody>
    </Card>
  );
}

6. TypeScript Support

Your project already has TypeScript configured, so the calendar will work seamlessly with your existing setup. All types are included in the package.

⚡ Ready to Use!

Your project is perfectly set up for the calendar package. Just install it and start using it immediately! 🚀

Quick Start

Single Calendar

import { Calendar } from '@zip_co/react-calendar';

function App() {
  const handleDateSelect = (date: Date) => {
    console.log('Selected date:', date);
  };

  return (
    <Calendar
      system="persian"
      range={true}
      disablePast={true}
      onDateSelect={handleDateSelect}
      theme="light"
      size="md"
    />
  );
}

Multiple Independent Calendars

import { MultiCalendar } from '@zip_co/react-calendar';

function App() {
  const calendars = [
    {
      id: "persian-calendar",
      config: {
        system: "persian",
        rangeMode: true,
        disablePast: true,
        weekStart: 0,
        initialDate: new Date(),
      },
      props: {
        theme: "light",
        size: "md",
        ariaLabel: "Persian Calendar",
      }
    },
    {
      id: "gregorian-calendar", 
      config: {
        system: "gregorian",
        rangeMode: false,
        disablePast: false,
        weekStart: 1,
        initialDate: new Date(),
      },
      props: {
        theme: "dark",
        size: "md",
        ariaLabel: "Gregorian Calendar",
      }
    }
  ];

  return (
    <MultiCalendar 
      calendars={calendars}
      layout="grid"
      gap={4}
    />
  );
}

Using CalendarProvider Directly

import { CalendarProvider, useCalendarContext } from '@zip_co/react-calendar';

function CustomCalendar() {
  const cal = useCalendarContext();
  
  return (
    <div>
      <h2>{cal.monthName} {cal.yearNumber}</h2>
      {/* Your custom calendar UI */}
    </div>
  );
}

function App() {
  return (
    <CalendarProvider config={{
      system: "persian",
      rangeMode: true,
      disablePast: true,
    }}>
      <CustomCalendar />
    </CalendarProvider>
  );
}

API Reference

Calendar Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | system | "persian" \| "gregorian" | "persian" | Calendar system | | range | boolean | false | Enable date range selection | | disablePast | boolean | false | Disable past dates | | disableFuture | boolean | false | Disable future dates | | weekStart | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 0 | First day of week | | minDate | Date \| string | - | Minimum selectable date | | maxDate | Date \| string | - | Maximum selectable date | | initialDate | Date \| string | new Date() | Initial displayed date | | theme | "light" \| "dark" \| "auto" | "light" | Visual theme | | size | "sm" \| "md" \| "lg" | "md" | Calendar size | | variant | "default" \| "minimal" \| "bordered" | "default" | Visual variant |

MultiCalendar Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | calendars | CalendarInstance[] | - | Array of calendar configurations | | layout | "horizontal" \| "vertical" \| "grid" | "grid" | Layout arrangement | | gap | number | 4 | Gap between calendars |

CalendarProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | config | CalendarConfig | - | Calendar configuration | | children | ReactNode | - | Child components |

State Management

This library uses React Context instead of Zustand for state management. Each calendar instance has its own isolated state through CalendarProvider.

Key Benefits:

• ✅ No External Dependencies: Removed Zustand dependency
• ✅ Isolated State: Each calendar instance is independent
• ✅ Better Performance: React Context optimization
• ✅ TypeScript Support: Full type safety
• ✅ Easy Testing: Standard React testing patterns

Migration from Zustand

If you were using the previous version with Zustand:

// Old (with Zustand)
import { useCalendar } from '@zip_co/react-calendar';

function MyComponent() {
  const cal = useCalendar({ system: "persian" });
  // ...
}

// New (with Context)
import { CalendarProvider, useCalendarContext } from '@zip_co/react-calendar';

function MyComponent() {
  return (
    <CalendarProvider config={{ system: "persian" }}>
      <CalendarContent />
    </CalendarProvider>
  );
}

function CalendarContent() {
  const cal = useCalendarContext();
  // ...
}

Styling

The library uses Tailwind CSS for styling. You can customize the appearance using:

• theme prop for light/dark/auto themes
• size prop for sm/md/lg sizes
• variant prop for default/minimal/bordered styles
• classes prop for custom CSS classes
• className prop for container styling

Browser Support

• Chrome 88+
• Firefox 85+
• Safari 14+
• Edge 88+

License

Troubleshooting

Common Issues

1. "use client" Directive Warning

If you see warnings about "use client" directives being ignored during build, this is normal for library builds and doesn't affect functionality.

2. Tailwind CSS Classes Not Applied

Make sure your Tailwind CSS configuration includes the library path:

module.exports = {
  content: [
    // ... your existing paths
    './node_modules/@zip_co/react-calendar/**/*.{js,ts,jsx,tsx}',
  ],
}

3. Persian Calendar Not Working

Ensure you have react-date-object installed:

npm install react-date-object@^2.1.9

4. Icons Not Showing

Make sure you have Heroicons installed:

npm install @heroicons/react@^2.2.0

5. TypeScript Errors

The library includes TypeScript definitions. If you encounter type errors:

// Make sure your tsconfig.json includes the library types
{
  "compilerOptions": {
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
  }
}

Demo

🎨 Live Storybook Demo: https://zipmip08.github.io/calendar-lib/

You can see interactive examples of all components with different configurations and use cases.

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

Changelog

v1.1.5

• ✅ Removed Zustand dependency, now uses React Context
• ✅ Added Persian calendar support
• ✅ Added multiple calendar instances support
• ✅ Added disableFuture functionality
• ✅ Improved TypeScript support
• ✅ Better performance with React Context

v1.0.0

• Initial release with basic calendar functionality

🚀 Publishing

This package is automatically published to NPM when you push a new version tag to GitHub.

Automatic Publishing

1. Create a version tag (triggers automatic publish):

   git tag v1.2.3
   git push origin v1.2.3

2. Or use manual publish workflow:

   • Go to GitHub Actions → Manual Publish to NPM
   • Choose version bump type (patch/minor/major)
   • Click "Run workflow"

Prerequisites for Publishing

1. NPM Token Setup:

   • Go to npmjs.com → Access Tokens → Generate New Token
   • Create token with "Automation" or "Publish" scope
   • Add token to GitHub repository secrets as NPM_TOKEN

2. GitHub Repository Setup:

   • Repository should be public or you should have NPM organization access
   • GitHub Actions should be enabled

Version Management

• Patch (1.2.3 → 1.2.4): Bug fixes
• Minor (1.2.3 → 1.3.0): New features (backward compatible)
• Major (1.2.3 → 2.0.0): Breaking changes

License

MIT