@samirkoirala/bs-calendar-react

A comprehensive React and React Native library for Bikram Sambat (Nepali calendar) with built-in holidays support. Fully cross-platform compatible.

✨ Features

• 🗓️ Accurate BS to AD conversion and vice versa
• 🎉 Built-in Nepali holidays with complete data
• 📅 Calendar grid generation with month navigation
• 🕐 Cross-platform timezone handling (Asia/Kathmandu)
• ⚛️ React hook for seamless integration
• 📱 Full React Native support (iOS, Android, Web, Windows, macOS)
• 📱 TypeScript support with complete type definitions
• 🚀 Lightweight and performant

🌏 Platform Support

✅ React: Web applications
✅ React Native: iOS, Android, Web, Windows, macOS
✅ Cross-platform: Works seamlessly everywhere
✅ TypeScript: Full type definitions included

📦 Installation

npm install @samirkoirala/bs-calendar-react
# or
yarn add @samirkoirala/bs-calendar-react

🚀 Quick Start

React/Web Usage

import React from 'react';
import { useCalendar } from '@samirkoirala/bs-calendar-react';

function CalendarComponent() {
  const { 
    today, 
    monthsWithHolidays, 
    currentBikYear, 
    currentBikMonth 
  } = useCalendar({});

  return (
    <div>
      <h2>Today: {today.date}</h2>
      <h3>BS Date: {currentBikYear}-{currentBikMonth}</h3>
      
      {monthsWithHolidays.map((day, index) => (
        <div key={index} className={day.holiday?.length ? 'holiday' : ''}>
          <span>Day {day.day}</span>
          {day.holiday?.map(h => <span key={h}>{h}</span>)}
        </div>
      ))}
    </div>
  );
}

React Native Usage

import React from 'react';
import { View, Text, ScrollView } from 'react-native';
import { useCalendar } from '@samirkoirala/bs-calendar-react';

export default function CalendarScreen() {
  const { today, monthsWithHolidays } = useCalendar({});

  return (
    <ScrollView style={{ flex: 1, padding: 16 }}>
      <Text style={{ fontSize: 24, fontWeight: 'bold' }}>
        Nepali Calendar
      </Text>
      <Text style={{ fontSize: 18 }}>Today: {today.date}</Text>

      {monthsWithHolidays.map((day, index) => (
        <View key={index} style={{ 
          padding: 8, 
          backgroundColor: day.holiday?.length ? '#ffebee' : 'white' 
        }}>
          <Text>Day {day.day}</Text>
          {day.holiday?.length > 0 && (
            <Text style={{ color: '#d32f2f' }}>
              {day.holiday.join(', ')}
            </Text>
          )}
        </View>
      ))}
    </ScrollView>
  );
}

📚 API Reference

useCalendar(options)

Main React hook for calendar functionality.

interface Props {
  year?: number;   // Bikram Sambat year
  month?: number;  // Bikram Sambat month (1-12)
}

const {
  today,              // Today's date info
  monthsWithHolidays, // Calendar days with holidays
  currentBikYear,     // Current BS year
  currentBikMonth,    // Current BS month
  currentBikDay,      // Current BS day
  getThisMonths,      // Function to get current month days
} = useCalendar({ year: 2081, month: 3 });

Utility Functions

import { 
  getCurrentDate,
  daysInMonth,
  bikramSambat 
} from '@samirkoirala/bs-calendar-react';

// Get current BS date
const today = getCurrentDate();
// { year: 2082, month: 3, day: 27 }

// Get days in a specific month
const days = daysInMonth(2082, 3); // 32 days (Asadh can have 32 days!)

// Direct converter access
const bsDate = bikramSambat.toBik('2025-07-11');
const adDate = bikramSambat.toGreg(2082, 3, 27);

🌟 Unique Features

Bikram Sambat Calendar Specifics

• Variable month lengths: BS months can have 29-32 days
• 32-day months: Months like Asadh (असार), Jestha (जेठ) can have 32 days
• Accurate holidays: Complete Nepali holiday calendar included

Month Names & Numbers

| Month | English | Nepali | Typical Days | |-------|---------|--------|--------------| | 1 | Baisakh | बैशाख | 30-31 | | 2 | Jestha | जेठ | 31-32 | | 3 | Asadh | असार | 31-32 | | 4 | Shrawan | श्रावण | 31-32 | | 5 | Bhadra | भदौ | 31 | | 6 | Ashwin | आश्विन | 30-31 | | 7 | Kartik | कार्तिक | 29-30 | | 8 | Mangsir | मंसिर | 29-30 | | 9 | Poush | पुष | 29-30 | | 10 | Magh | माघ | 29-30 | | 11 | Falgun | फाल्गुण | 29-30 | | 12 | Chaitra | चैत्र | 30-31 |

📱 React Native Documentation

For detailed React Native usage, examples, and platform-specific guides:

• React Native Usage Guide
• Example App Setup

🔧 Advanced Usage

Month Navigation

const [year, setYear] = useState(2081);
const [month, setMonth] = useState(3);

const { monthsWithHolidays } = useCalendar({ year, month });

const nextMonth = () => {
  if (month < 12) setMonth(month + 1);
  else { setYear(year + 1); setMonth(1); }
};

Holiday Filtering

const { monthsWithHolidays } = useCalendar({});
const holidays = monthsWithHolidays.filter(day => day.holiday?.length > 0);

🎯 TypeScript Support

Full TypeScript definitions included:

interface IMonthDayWithHoliday {
  date: string;        // YYYY-MM-DD format
  month: number;       // Month number (1-12)
  day: number;         // Day number
  bs_date: string;     // Bikram Sambat date string
  holiday: string[];   // Array of holiday names
}

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📄 License

ISC License - see LICENSE file for details.

🙏 Credits

• Author: Pradip Chapagain
• Bikram Sambat Converter: Based on accurate BS calendar algorithms
• Holiday Data: Official Nepal holiday calendar

Made with ❤️ for the Nepali developer community