📅 Customizable, animated calendar widget including day, week, and month views.

| Navigation | Animation | | :-------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------: | | | |

| Callbacks | Changing the

VisibleDateRange

• Available Layouts
• Getting started
  • 0. General Information
  • 1. Define your

    Event

    s
  • 2. Create a

    DateController

    (optional)
  • 3. Create a

    TimeController

    (optional)
  • 4. Create your Timetable
• Theming
• Advanced Features
  • Drag and Drop
  • Time Overlays

Available Layouts

MultiDateTimetable

A Timetable widget that displays multiple consecutive days.

| Light Mode | Dark Mode | | :---------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------: | | | |

RecurringMultiDateTimetable

A Timetable widget that displays multiple consecutive days without their dates and without a week indicator.

| Light Mode | Dark Mode | | :------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------: | | | |

CompactMonthTimetable

A Timetable widget that displays

MonthWidget

| Light Mode | Dark Mode | | :------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------: | | | |

Getting started

0. General Information

Timetable doesn't care about any time-zone related stuff. All supplied

DateTime

isUtc

true

Some date/time-related parameters also have special suffixes:

• date

  : A

  DateTime

  with a time of zero.

• month

  : A

  DateTime

  with a time of zero and a day of one.

• timeOfDay

  : A

  Duration

  between zero and 24 hours.

• dayOfWeek

  : An

  int

  between one and seven (

  DateTime.monday

  through

  DateTime.sunday

  ).

Timetable currently offers localizations for Chinese, English, French, German, Hungarian, Italian, Japanese, Portuguese, and Spanish. Even if you're just supporting English in your app, you have to add Timetable's localization delegate to your

MaterialApp

CupertinoApp

WidgetsApp

MaterialApp(
  localizationsDelegates: [
    TimetableLocalizationsDelegate(),
    // Other delegates, e.g., `GlobalMaterialLocalizations.delegate`
  ],
  // ...
);

You want to contribute a new localization? Awesome! Please follow the steps listed in the doc comment of

TimetableLocalizationsDelegate

.

1. Define your

Event

s

Events are provided as instances of

Event

BasicEvent

Event

⚠️ Most of Timetable's classes accept a type-parameter

E extends Event

. Please set it to your chosen

Event

-subclass (e.g.,

BasicEvent

) to avoid runtime exceptions.

In addition, you also need a

Widget

BasicEvent

BasicEventWidget

2. Create a

DateController

Similar to a

ScrollController

TabController

DateController

DateController

VisibleDateRange

final myDateController = DateController(
  // All parameters are optional and displayed with their default value.
  initialDate: DateTimeTimetable.today(),
  visibleRange: VisibleDateRange.week(startOfWeek: DateTime.monday),
);

Don't forget to

dispose

your controller, e.g., in

State.dispose

!

Here are some of the available

VisibleDateRange

• VisibleDateRange.days

  : displays

  visibleDayCount

  consecutive days, snapping to every

  swipeRange

  days (aligned to

  alignmentDate

  ) in the range from

  minDate

  to

  maxDate

• VisibleDateRange.week

  : displays and snaps to whole weeks with a customizable

  startOfWeek

  in the range from

  minDate

  to

  maxDate

• VisibleDateRange.weekAligned

  : displays

  visibleDayCount

  consecutive days while snapping to whole weeks with a customizable

  firstDay

  in the range from

  minDate

  to

  maxDate

   – can be used, e.g., to display a five-day workweek

3. Create a

TimeController

Similar to the

DateController

TimeController

MultiDateTimetable

RecurringMultiDateTimetable

final myTimeController = TimeController(
  // All parameters are optional. By default, the whole day is revealed
  // initially and you can zoom in to view just a single minute.
  minDuration: 15.minutes, // The closest you can zoom in.
  maxDuration: 23.hours, // The farthest you can zoom out.
  initialRange: TimeRange(9.hours, 17.hours),
  maxRange: TimeRange(0.hours, 24.hours),
);

This example uses some of supercharged's extension methods on

int

to create a

Duration

more concisely.

Don't forget to

dispose

your controller, e.g., in

State.dispose

!

4. Create your Timetable widget

The configuration for Timetable's widgets is provided via inherited widgets. You can use a

TimetableConfig

TimetableConfig(
  // Required:
  dateController: _dateController,
  timeController: _timeController,
  eventBuilder: (context, event) => BasicEventWidget(event),
  child: MultiDateTimetable(),
  // Optional:
  eventProvider: (date) => someListOfEvents,
  allDayEventBuilder: (context, event, info) =>
      BasicAllDayEventWidget(event, info: info),
  callbacks: TimetableCallbacks(
    // onWeekTap, onDateTap, onDateBackgroundTap, onDateTimeBackgroundTap
  ),
  theme: TimetableThemeData(
    context,
    // startOfWeek: DateTime.monday,
    // See the "Theming" section below for more options.
  ),
)

And you're done 🎉

Theming

Timetable already supports light and dark themes out of the box, adapting to the ambient

ThemeData

TimetableThemeData

To apply your own theme, specify it in the

TimetableConfig

TimetableConfig(
  theme: TimetableThemeData(
    context,
    startOfWeek: DateTime.monday,
    dateDividersStyle: DateDividersStyle(
      context,
      color: Colors.blue.withOpacity(.3),
      width: 2,
    ),
    dateHeaderStyleProvider: (date) =>
        DateHeaderStyle(context, date, tooltip: 'My custom tooltip'),
    nowIndicatorStyle: NowIndicatorStyle(
      context,
      lineColor: Colors.green,
      shape: TriangleNowIndicatorShape(color: Colors.green),
    ),
    // See the "Theming" section below for more.
  ),
  // Other properties...
)

TimetableThemeData

and all component styles provide two constructors each:

• The default constructor takes a

  BuildContext

  and sometimes a day or month, using information from the ambient theme and locale to generate default values. You can still override all options via optional, named parameters.
• The named

  raw

  constructor is usually

  const

  and has required parameters for all options.

Advanced Features

Drag and Drop

You can easily make events inside the content area of

MultiDateTimetable

RecurringMultiDateTimetable

PartDayDraggableEvent

PartDayDraggableEvent(
  // The user started dragging this event.
  onDragStart: () {},
  // The event was dragged to the given [DateTime].
  onDragUpdate: (dateTime) {},
  // The user finished dragging the event and landed on the given [DateTime].
  onDragEnd: (dateTime) {},
  child: MyEventWidget(),
  // By default, the child is displayed with a reduced opacity when it's
  // dragged. But, of course, you can customize this:
  childWhileDragging: OptionalChildWhileDragging(),
)

Timetable doesn't automatically show a moving feedback widget at the current pointer position. Instead, you can customize this and, e.g., snap to multiples of 15 minutes. Have a look at the included example app where we implemented exactly that by displaying the drag feedback as a time overlay.

Time Overlays

In addition to displaying events,

MultiDateTimetable

RecurringMultiDateTimetable

TimetableConfig

TimetableConfig(
  timeOverlayProvider: (context, date) => [
    TimeOverlay(
      start: 0.hours,
      end: 8.hours,
      widget: ColoredBox(color: Colors.black12),
      position: TimeOverlayPosition.behindEvents, // the default, alternatively `inFrontOfEvents`
    ),
    TimeOverlay(
      start: 20.hours,
      end: 24.hours,
      widget: ColoredBox(color: Colors.black12),
    ),
  ],
  // Other properties...
)

The provider is just a function that receives a date and returns a list of

TimeOverlay