@samirkoirala/bs-calendar-react
Version:
A comprehensive React and React Native library for Bikram Sambat (Nepali) calendar with holidays support. Cross-platform compatible.
230 lines (175 loc) • 6.33 kB
Markdown
# @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.
[](https://badge.fury.io/js/@samirkoirala%2Fbs-calendar-react)
[](https://reactnative.dev/)
[](https://www.typescriptlang.org/)
## ✨ 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
```bash
npm install @samirkoirala/bs-calendar-react
# or
yarn add @samirkoirala/bs-calendar-react
```
## 🚀 Quick Start
### React/Web Usage
```typescript
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
```typescript
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.
```typescript
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
```typescript
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](./REACT_NATIVE.md)
- [Example App Setup](./EXAMPLE_APP.md)
## 🔧 Advanced Usage
### Month Navigation
```typescript
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
```typescript
const { monthsWithHolidays } = useCalendar({});
const holidays = monthsWithHolidays.filter(day => day.holiday?.length > 0);
```
## 🎯 TypeScript Support
Full TypeScript definitions included:
```typescript
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