Indonesia Holidays #

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

This package is developed by Panca Nugraha.

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 #

1. Navigate to the example folder:

   cd example
   

2. Install dependencies:

   flutter pub get
   

3. 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

Navigation #

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.

License #

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