Indonesia Holidays

pub package likes popularity

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

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.

Libraries

indonesia_holidays
ui_helpers