Indonesia Holidays

A Dart package to fetch Indonesian national holidays and check if specific dates are holidays using the Libur API.

Features

Get list of holidays for a specific year or month
Filter holidays by month
Get holiday dates as List
Check if a specific date is a holiday
Check if today or tomorrow is a holiday
Support for English language translation
UI helpers for Flutter integration (widgets and extensions)
Easy integration with Flutter/Dart applications

Getting started

Add this to your pubspec.yaml:

dependencies:
  indonesia_holidays: ^0.0.1

Then run:

flutter pub get

Usage

Get holidays for a year

import 'package:indonesia_holidays/indonesia_holidays.dart';

void main() async {
  List<Holiday> holidays = await IndonesiaHolidays.getHolidays(year: 2024);
  for (var holiday in holidays) {
    print('${holiday.date}: ${holiday.name}');
  }
}

Get holidays for a specific month

List<Holiday> holidays = await IndonesiaHolidays.getHolidaysForMonth(8, year: 2024);

Get holiday dates as DateTime list

List<DateTime> holidayDates = await IndonesiaHolidays.getHolidayDates(year: 2024);
for (var date in holidayDates) {
  print('Holiday on: $date');
}

Get holidays in English

List<Holiday> holidays = await IndonesiaHolidays.getHolidays(year: 2024, language: 'en');
for (var holiday in holidays) {
  print('${holiday.date}: ${holiday.name}');
}

Using UI Helpers

The package provides UI helpers for easy integration with Flutter widgets.

Check if a date is holiday using extension

DateTime date = DateTime(2024, 8, 17);
bool isHoliday = await date.isHoliday();
String? holidayName = await date.getHolidayName();

Display holiday list

HolidayListView(year: 2024, month: 8)

Custom holiday list items

HolidayListView(
  year: 2024,
  itemBuilder: (context, holiday) => Card(
    child: ListTile(
      title: Text(holiday.name, style: TextStyle(fontWeight: FontWeight.bold)),
      subtitle: Text(holiday.date),
      leading: Icon(Icons.calendar_today, color: Colors.red),
    ),
  ),
)

Show today's holiday status

TodayHolidayStatus()

Custom holiday list with separators and performance optimization

HolidayListView(
  year: 2024,
  separatorBuilder: (context, index) => Divider(),
  itemExtent: 80.0, // For performance if all items same height
  cacheExtent: 200.0, // Pre-load more items
  physics: BouncingScrollPhysics(), // Custom scroll physics
  padding: EdgeInsets.all(16.0),
)

Custom holiday status with animation

TodayHolidayStatus(
  animationDuration: Duration(seconds: 1),
  animationCurve: Curves.elasticOut,
  useAnimation: true,
  holidayBuilder: (context, check) => AnimatedContainer(
    duration: Duration(milliseconds: 500),
    color: Colors.green,
    padding: EdgeInsets.all(20),
    child: Text('Holiday: ${check.holidayList.join(', ')}'),
  ),
)

Horizontal scrolling holiday list

HolidayListView(
  year: 2024,
  scrollDirection: Axis.horizontal,
  shrinkWrap: true,
  itemBuilder: (context, holiday) => Container(
    width: 200,
    margin: EdgeInsets.all(8),
    child: Card(child: Center(child: Text(holiday.name))),
  ),
)

Testing the Visual UI Helpers

To see the visual appearance of the UI helpers provided by this package, you can run the included example app:

How to Run the Example App

Navigate to the example folder:
```
cd example
```
Install dependencies:
```
flutter pub get
```
Run the application:
```
flutter run
```

Alternatively, Using Flutter Run from Root Directory

If you want to run from the package's root directory:

flutter run --target=example/lib/main.dart

Initial Preparation

Make sure you have a connected device/emulator or a running simulator.

Features Available in the Example App

Today Status Page: Displays the TodayHolidayStatus widget that shows whether today is a holiday or not
Holiday List Page: Displays the HolidayListView widget with filtering capabilities by year, month, and language
Date Check Page: Interactive demo where users can select a date from the date picker and check if that date is a holiday

The example app uses BottomNavigationBar to switch between the 3 main pages.

Screenshot Preview

This application demonstrates the real implementation of UI helpers in a Flutter app context, including:

Loading states with CircularProgressIndicator
Error handling
Material Design styling
Responsive layout
Interactive date selection

Display upcoming holidays

UpcomingHolidaysWidget(limit: 3)

Check if a date is a holiday

HolidayCheck check = await IndonesiaHolidays.checkDate(2024, 8, 17);
if (check.isHoliday) {
  print('Holiday: ${check.holidayList.join(', ')}');
} else {
  print('Not a holiday');
}

Check today

HolidayCheck today = await IndonesiaHolidays.isTodayHoliday();
print('Today is holiday: ${today.isHoliday}');

Check tomorrow

HolidayCheck tomorrow = await IndonesiaHolidays.isTomorrowHoliday();
print('Tomorrow is holiday: ${tomorrow.isHoliday}');

API Reference

Classes

Holiday: Represents a holiday with date and name.
HolidayCheck: Result of checking a date, with date, isHoliday, and holidayList.
IndonesiaHolidays: Main class with static methods.

Methods

getHolidays({int? year, int? month, String language = 'id'}): Get list of holidays. Language can be 'id' or 'en'.
getHolidaysForMonth(int month, {int? year, String language = 'id'}): Get holidays for a specific month.
getHolidayDates({int? year, int? month}): Get holiday dates as List
checkDate(int year, int month, int day): Check specific date.
isTodayHoliday(): Check if today is holiday.
isTomorrowHoliday(): Check if tomorrow is holiday.

Additional information

This package uses the free API from libur.deno.dev, which provides official Indonesian holiday data.

For more information, visit the API documentation.

This package is developed by Panca Nugraha.

License

This package is open source, check the LICENSE file for details.