# table_calendar 3.3.0

Highly customizable, feature-packed calendar widget for Flutter.




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add table_calendar
```
Published: 2026-10-01T12:14:32.358152Z
Expected archive SHA-256: c46a7b6e853154bde099cc6b9d151268a721b16c24e6cacc5c9ee8dfe6a55243

Available in cache; verification: upstream_checksum
## Direct dependencies
- flutter: map[sdk:flutter]
- intl: >=0.20.3 <0.21.0
- simple_gesture_detector: ^0.2.0

## Package README (untrusted upstream documentation)
# TableCalendar

[![Pub Package](https://img.shields.io/pub/v/table_calendar.svg?style=flat-square)](https://pub.dartlang.org/packages/table_calendar)
[![Awesome Flutter](https://img.shields.io/badge/Awesome-Flutter-52bdeb.svg?longCache=true&style=flat-square)](https://github.com/Solido/awesome-flutter)

Highly customizable, feature-packed calendar widget for Flutter.

| ![Image](https://raw.githubusercontent.com/aleksanderwozniak/table_calendar/assets/table_calendar_styles.gif) | ![Image](https://raw.githubusercontent.com/aleksanderwozniak/table_calendar/assets/table_calendar_builders.gif) |
| :------------: | :------------: |
| **TableCalendar** with custom styles | **TableCalendar** with custom builders |

## Features

* Extensive, yet easy to use API
* Preconfigured UI with customizable styling
* Custom selective builders for unlimited UI design
* Locale support
* Range selection support
* Multiple selection support
* Dynamic events and holidays
* Vertical autosizing - fit the content, or fill the viewport
* Multiple calendar formats (month, two weeks, week)
* Horizontal swipe boundaries (first day, last day)

## Usage

Make sure to check out [examples](https://github.com/aleksanderwozniak/table_calendar/tree/master/example/lib/pages) and [API docs](https://pub.dev/documentation/table_calendar/latest/) for more details.

### Installation

Add the following line to `pubspec.yaml`:

```yaml
dependencies:
  table_calendar: ^3.3.0
```

### Basic setup

*The complete example is available [here](https://github.com/aleksanderwozniak/table_calendar/blob/master/example/lib/pages/basics_example.dart).*

**TableCalendar** requires you to provide `firstDay`, `lastDay` and `focusedDay`:

* `firstDay` is the first available day for the calendar. Users will not be able to access days before it.
* `lastDay` is the last available day for the calendar. Users will not be able to access days after it.
* `focusedDay` is the currently targeted day. Use this property to determine which month should be currently visible.

```dart
TableCalendar(
  firstDay: DateTime.utc(2010, 10, 16),
  lastDay: DateTime.utc(2030, 3, 14),
  focusedDay: DateTime.now(),
);
```

#### Adding interactivity

You will surely notice that previously set up calendar widget isn't quite interactive - you can only swipe it horizontally, to change the currently visible month. While it may be sufficient in certain situations, you can easily bring it to life by specifying a couple of callbacks.

Adding the following code to the calendar widget will allow it to respond to user's taps, marking the tapped day as selected:

```dart
selectedDayPredicate: (day) {
  return isSameDay(_selectedDay, day);
},
onDaySelected: (selectedDay, focusedDay) {
  setState(() {
    _selectedDay = selectedDay;
    _focusedDay = focusedDay; // update `_focusedDay` here as well
  });
},
```

In order to dynamically update visible calendar format, add those lines to the widget:

```dart
calendarFormat: _calendarFormat,
onFormatChanged: (format) {
  setState(() {
    _calendarFormat = format;
  });
},
```

Those two changes will make the calendar interactive and responsive to user's input.

#### Updating focusedDay

Setting `focusedDay` to a static value means that whenever **TableCalendar** widget rebuilds, it will use that specific `focusedDay`. You can quickly test it by using hot reload: set `focusedDay` to `DateTime.now()`, swipe to next month and trigger a hot reload - the calendar will "reset" to its initial state. To prevent this from happening, you should store and update `focusedDay` whenever any callback exposes it.

Add this one callback to complete the basic setup:

```dart
onPageChanged: (focusedDay) {
  _focusedDay = focusedDay;
},
```

It is worth noting that you don't need to call `setState()` inside `onPageChanged()` callback. You should just update the stored value, so that if the widget gets rebuilt later on, it will use the proper `focusedDay`.

*The complete example is available [here](https://github.com/aleksanderwozniak/table_calendar/blob/master/example/lib/pages/basics_example.dart). You can find other examples [here](https://github.com/aleksanderwozniak/table_calendar/tree/master/example/lib/pages).*

### Events

*The complete example is available [here](https://github.com/aleksanderwozniak/table_calendar/blob/master/example/lib/pages/events_example.dart).*

You can supply custom events to **TableCalendar** widget. To do so, use `eventLoader` property - you will be given a `DateTime` object, to which you need to assign a list of events.

```dart
eventLoader: (day) {
  return _getEventsForDay(day);
},
```

`_getEventsForDay()` can be of any implementation. For example, a `Map<DateTime, List<T>>` can be used:

```dart
List<Event> _getEventsForDay(DateTime day) {
  return events[day] ?? [];
}
```

One thing worth remembering is that `DateTime` objects consist of both date and time parts. In many cases this time part is redundant for calendar related aspects.

If you decide to use a `Map`, I suggest making it a `LinkedHashMap` - this will allow you to override equality comparison for two `DateTime` objects, comparing them just by their date parts:

```dart
final events = LinkedHashMap(
  equals: isSameDay,
  hashCode: getHashCode,
)..addAll(eventSource);
```

#### Cyclic events

`eventLoader` allows you to easily add events that repeat in a pattern. For example, this will add an event to every Monday:

```dart
eventLoader: (day) {
  if (day.weekday == DateTime.monday) {
    return [Event('Cyclic event')];
  }

  return [];
},
```

#### Events selected on tap

Often times having a sublist of events that are selected by tapping on a day is desired. You can achieve that by using the same method you provided to `eventLoader` inside of `onDaySelected` callback:

```dart
void _onDaySelected(DateTime selectedDay, DateTime focusedDay) {
  if (!isSameDay(_selectedDay, selectedDay)) {
    setState(() {
      _focusedDay = focusedDay;
      _selectedDay = selectedDay;
      _selectedEvents = _getEventsForDay(selectedDay);
    });
  }
}
```

*The complete example is available [here](https://github.com/aleksanderwozniak/table_calendar/blob/master/example/lib/pages/events_example.dart).*

### Custom UI with CalendarBuilders

To customize the UI with your own widgets, use [CalendarBuilders](https://pub.dev/documentation/table_calendar/latest/table_calendar/CalendarBuilders-class.html). Each builder can be used to selectively override the UI, allowing you to implement highly specific designs with minimal hassle.

You can return `null` from any builder to use the default style. For example, the following snippet will override only the Sunday's day of the week label (Sun), leaving other dow labels unchanged:

```dart
calendarBuilders: CalendarBuilders(
  dowBuilder: (context, day) {
    if (day.weekday == DateTime.sunday) {
      final text = DateFormat.E().format(day);

      return Center(
        child: Text(
          text,
          style: TextStyle(color: Colors.red),
        ),
      );
    }
  },
),
```

### Locale

To display the calendar in desired language, use `locale` property.
If you don't specify it, a default locale will be used.

#### Initialization

Before you can use a locale, you might need to initialize date formatting.

A simple way of doing it is as follows:

* First of all, add [intl](https://pub.dev/packages/intl) package to your pubspec.yaml file
* Then make modifications to your `main()`:

```dart
import 'package:intl/date_symbol_data_local.dart';

void main() {
  initializeDateFormatting().then((_) => runApp(MyApp()));
}
```

After those two steps your app should be ready to use **TableCalendar** with different languages.

#### Specifying a language

To specify a language, simply pass it as a String code to `locale` property.

For example, this will make **TableCalendar** use Polish language:

```dart
TableCalendar(
  locale: 'pl_PL',
),
```

| ![Image](https://raw.githubusercontent.com/aleksanderwozniak/table_calendar/assets/en_US.png) | ![Image](https://raw.githubusercontent.com/aleksanderwozniak/table_calendar/assets/pl_PL.png) | ![Image](https://raw.githubusercontent.com/aleksanderwozniak/table_calendar/assets/fr_FR.png) | ![Image](https://raw.githubusercontent.com/aleksanderwozniak/table_calendar/assets/zh_CN.png) |
| :------------: | :------------: | :------------: | :------------: |
| `'en_US'` | `'pl_PL'` | `'fr_FR'` | `'zh_CN'` |

Note, that if you want to change the language of `FormatButton`'s text, you have to do this yourself. Use `availableCalendarFormats` property and pass the translated Strings there. Use i18n method of your choice.

You can also hide the button altogether by setting `formatButtonVisible` to false.

## Changelog
## [3.3.0]

* Added explicit generic type to CellContent widget
* Changed locale field type from dynamic to String? (matching intl 0.20.3)
* Set intl dependency bounds to ">=0.20.3 <0.21.0"
* Updated analyzer and linter rules
* Updated tests

## [3.2.1]

* Upgraded Android and iOS build config for the example project
* Adjusted header layout in complex_example

## [3.2.0]

* Added loadEventsForDisabledDays property to enable loading events for disabled days as well
* Fixed empty weekendDays assertion issue
* Updated intl version to 0.20.0

## [3.1.3]

* Updated gradle config for example project
* Added and applied lint rules, refactored code

## [3.1.2]

* Added dayTextFormatter property to CalendarStyle that allows to customize the text within day cells
* Reverted the default day cell's text formatting to just the day's number

## [3.1.1]

* Added cell text localization based on current locale

## [3.1.0]

* Upgraded to Dart 3
* Updated intl version to 0.19.0

## [3.0.9]

* Updated intl version to 0.18.0
* Added explicit android:exported value to AndroidManifest

## [3.0.8]

* Added tablePadding property to CalendarStyle

## [3.0.7]

* Added week numbering feature

## [3.0.6]

* Fixed issue with missing Flutter Web platform tag

## [3.0.5]

* Added a visual indicator to FormatButton
* Header buttons are now platform-aware

## [3.0.4]

* Updated dependencies
* Removed deprecated fields

## [3.0.3]

* Added semantic label to prioritizedBuilder
* Added tableBorder property to CalendarStyle
* Added cellAlignment property to CalendarStyle
* Added cellPadding property to CalendarStyle

## [3.0.2]

* Improved semantic labels for screen readers

## [3.0.1]

* Added pageAnimationEnabled property
* Added currentDay property to improve widget testability

## [3.0.0]

* Migrated to null safety
* Removed CalendarController
* Improved horizontal scrolling
* Improved widget performance
* Improved documentation
* Added date range selection
* Added multiple date selection
* Added selective CalendarBuilders
* Added firstDay and lastDay scroll boundaries
* Added shouldFillViewport property
* Added sixWeekMonthsEnforced property
* Added more options to customize calendar's behavior

## [2.3.3]

* Updated dependencies

## [2.3.2]

* Added previousPage and nextPage methods to CalendarController

## [2.3.1]

* Added chevron visibility properties to HeaderStyle
* Added cellMargin property to CalendarStyle
* Added eventDayStyle property to CalendarStyle
* Added availableCalendarFormats dynamic update
* Added optional BoxDecoration for each calendar row
* Added optional BoxDecoration for days of week row

## [2.3.0]

* Migrated to AndroidX
* Added holidays to onDaySelected callback
* Replaced deprecated overflow property with clipBehavior

## [2.2.3]

* Added onCalendarCreated callback

## [2.2.2]

* Added highlightSelected property to CalendarStyle
* Added highlightToday property to CalendarStyle

## [2.2.1]

* Added onHeaderTapped callback
* Added onHeaderLongPressed callback
* Fixed endDay issue

## [2.2.0]

* Added LongPress Gesture support
* Added option to disable days based on a predicate
* Added option to hide DaysOfWeek row
* Added header Decoration
* Added headerMargin property
* Added headerPadding property
* Added contentPadding property

## [2.1.0]

* Added dynamic events and holidays
* Added StartingDayOfWeek for every weekday
* Added support for custom weekend days
* Added dowWeekdayBuilder and dowWeekendBuilder
* Broadened intl dependency bounds
* markersMaxAmount no longer affects markersBuilder
* Fixed twoWeeks format programmatic issue
* Fixed visibleDays issue
* Fixed null dispose issue

## [2.0.2]

* Updated dependencies

## [2.0.1]

* Fixed issue with custom markers for holidays

## [2.0.0]

* Added CalendarController - TableCalendar now features complete programmatic control
* Removed redundant properties
* Updated example project
* Updated README

## [1.2.5]

* Fixed last day of month animation issue

## [1.2.4]

* Improved DateTime logic
* Event markers can now be set to overflow cell boundaries

## [1.2.3]

* Added startDay and endDay to allow users to specify available date range
* Added unavailableStyle and unavailableDayBuilder for days outside of given date range
* Added onUnavailableDaySelected callback
* Unavailable days will not display event markers

## [1.2.2]

* Fixed issue with Markers being null

## [1.2.1]

* RowHeight can now be set as a fixed value
* MaxMarkersAmount will now affect MarkersBuilder

## [1.2.0]

* Added holiday support
* Added holiday usage guide
* Improved custom markers builder
* Added rendering priority customization
* Added FormatButton behavior customization

## [1.1.4]

* Added TextBuilders for Header and DOW panel
* Improved vertical swipe behavior

## [1.1.3]

* Added title text customization with format skeleton
* Added day of the week text customization with format skeleton
* Rolled-back intl dependency

## [1.1.2]

* Added locale support
* Added locale usage guide
* Updated example project

## [1.1.1]

* Improved chevron customization

## [1.1.0]

* Added programmatic selectedDay
* Removed onFormatChanged callback - it is now integrated into onVisibleDaysChanged callback
* Improved onVisibleDaysChanged behavior
* Fixed issue with empty Calendar row
* Changed default FormatButton texts
* Updated example project

## [1.0.2]

* FormatButton text can now be customized

## [1.0.1]

* Fixed CalendarFormat issue when not using a callback

## [1.0.0]

* Added custom Builders API
* Added DateTime truncation logic
* onDaySelected callback now contains list of events associated with that day
* Added onVisibleDaysChanged callback
* SwipeConfig can now be customized
* Days outside of current month can be shown/hidden
* Refactored code
* Updated example project

## [0.3.2]

* Added SwipeToExpand for CalendarFormat
* AvailableGestures can now be specified (none, horizontalSwipe, verticalSwipe, all)
* Fixed styling issue with SelectedDay on weekends

## [0.3.1]

* Added slide animation for CalendarFormat
* CalendarFormat animation can now be specified (slide, scale)
* Added Monday-Sunday week format
* Week format can now be specified with StartingDayOfWeek enum

## [0.3.0]

* Any style can now be customized
* Grouped properties into Classes
* Refactored code for better readability
* Added full documentation

## [0.2.2]

* Added optional initial Date (defaults to DateTime.now())

## [0.2.1]

* Added animated Swipe gesture
* CalendarFormat can now be enforced programmatically

## [0.2.0]

* Added animations to CalendarFormat change
* Added animations to Date selection
* Added new CalendarFormat - TwoWeeks
* Available CalendarFormats can now be specified

## [0.1.4]

* Refactored code
* Updated example project

## [0.1.3]

* Added chevron button customization
* Calendar header can be hidden now

## [0.1.2]

* Added OnFormatChanged callback

## [0.1.1]

* Added CalendarFormat button customization

## [0.1.0]

* Added CalendarFormat button - toggle between month view and week view
* Additional customization is now available

## [0.0.2]

* Revamped example
* Improved description

## [0.0.1] - Initial release

* Fully working TableCalendar; example included