Views topic

Views

This is part of the kalender documentation.

The view configuration decides which calendar you get and how it behaves when you switch away from it. For what the user can do inside a view, see Interaction.

Switching between views

Switch between views by passing a different ViewConfiguration to KalenderView. What carries over on a switch is controlled per dimension:

  • Date (all views): dateTransition. Use DateTransition.carryFocus (default, follows your current date) or DateTransition.restorePerView (each view reopens its own last date, matched by name).
  • Scroll & zoom (multi-day views): scrollTransition / zoomTransition. Use preserve (default), reset, or restorePerView.

For custom logic, provide a dateResolver / scrollResolver / zoomResolver. Each overrides the matching enum. kCarryFocusDate(transition) gives you the default carry-focus date to build on.

initialDateTime is only used when the calendar is first built. To show a fixed date on a switch, return it from a dateResolver. The resolvers also run when the location changes, which transition.locationChanged reports.

Shared options

All configurations accept:

  • displayRange: the total date range the calendar can navigate within (e.g. Jan 2024 to Dec 2025). Defaults to 1 January two years back through 1 January two years ahead.
  • initialDateTime: the date to show on first render. Defaults to DateTime.now().
  • multiDayRule: what counts as a multi-day event and so renders in the multi-day header rather than the day timeline. Defaults to events lasting 24 hours or more (MultiDayRule.minimumDuration). MultiDayRule.calendarDays() instead counts anything that crosses midnight. A single event can override the rule, or state that it is all-day and skip the rule entirely, see Multi-day and all-day events.
  • name: identifies the view. Each constructor sets one already ('Day', 'Week', 'Work Week', 'Custom', 'Free Scroll', 'Month', 'Schedule'). It is what DateTransition.restorePerView matches on, so two configurations that should restore separately need different names. It is also a ready-made label for a view switcher, see Building the surrounding UI.
  • nowCallback: overrides how the calendar resolves "now", see Now Callback.
MultiDayViewConfiguration.week(
  displayRange: KalenderDateTimeRange(
    start: DateTime(2024, 1, 1),
    end: DateTime(2025, 12, 31),
  ),
  initialDateTime: DateTime(2024, 6, 15),
)

MultiDay View

Displays one or more days with time on the vertical axis.

Constructor Description
MultiDayViewConfiguration.singleDay() Single day
MultiDayViewConfiguration.week() A week, 7 days by default
MultiDayViewConfiguration.workWeek() Monday to Friday, 5 days by default
MultiDayViewConfiguration.custom(numberOfDays: n) Custom number of days
MultiDayViewConfiguration.freeScroll(numberOfDays: n) Scrolls freely across days, without page snaps

These views also control which hours exist, where the day opens vertically, and how tall an hour is:

  • timeOfDayRange: the hours the body lays out. Defaults to KalenderTimeRange.allDay(), which is 00:00 to 23:59. Narrowing it makes the page shorter. Positions are measured from start, so an event falling outside the range is drawn outside the page and clipped. Narrow it only when events cannot fall outside it.
  • initialTimeOfDay: the time at the top of the viewport on first render. Defaults to midnight. The offset is measured from timeOfDayRange.start, so keep this value inside the range.
  • initialHeightPerMinute: the starting zoom, in logical pixels per minute. Defaults to 0.7, giving a 42 pixel hour. Change it later through the controller, see Zoom.
  • firstDayOfWeek: which day a week starts on, as DateTime.monday through DateTime.sunday. Defaults to DateTime.monday. Applies to week, singleDay and custom. workWeek and freeScroll fix it themselves.
  • numberOfDays: how many days a page shows. week and workWeek take 1 through 7 and drop days off the end of the page without changing the pagination, so week(numberOfDays: 6) shows Monday to Saturday and still turns a week at a time. custom and freeScroll require it and page by it, so they take any number. singleDay fixes it at 1.
MultiDayViewConfiguration.week(
  // Working hours only. The timeline runs 08:00 to 18:00 and nothing else exists.
  timeOfDayRange: KalenderTimeRange(
    start: const KalenderTime(hour: 8, minute: 0),
    end: const KalenderTime(hour: 18, minute: 0),
  ),
  initialTimeOfDay: const KalenderTime(hour: 8, minute: 0),
  initialHeightPerMinute: 0.7,
  firstDayOfWeek: DateTime.sunday,
)

Month View

Shows a whole month, weeks as rows.

Constructor Description
MonthViewConfiguration.singleMonth() Single month

Month view can be adjusted with firstDayOfWeek and showWeekNumbers:

MonthViewConfiguration.singleMonth(
  initialDateTime: DateTime(2025, 1, 1),
  firstDayOfWeek: DateTime.monday,
  showWeekNumbers: true,
)

When showWeekNumbers is enabled, the month body adds a leading gutter with one week number per visible row while keeping the day grid at 7 columns.

Schedule View

Presents events in a chronological scrollable list.

Constructor Description
ScheduleViewConfiguration.continuous() Single continuous list
ScheduleViewConfiguration.paginated() Paginated by month

Per-view configuration

KalenderHeader and KalenderBody accept view-specific configuration objects:

View Header config class Body config class
MultiDay MultiDayHeaderConfiguration MultiDayBodyConfiguration
Month None MonthBodyConfiguration
Schedule None ScheduleBodyConfiguration

Both also accept interaction. KalenderBody additionally accepts snapping, which the header has no equivalent of. Both are covered in Interaction.

Each configuration class has defaults that suit most apps. The references below spell every option out at its default value, so a block copied whole leaves the calendar exactly as it was. Change only the lines you care about.

MultiDayHeaderConfiguration 
KalenderHeader(
  multiDayHeaderConfiguration: MultiDayHeaderConfiguration(
    showTiles: true,
    allowSingleDayEvents: false,
    tileHeight: 24,
    eventPadding: EdgeInsets.only(left: 0, right: 4, bottom: 2),
    pageTriggerConfiguration: PageTriggerConfiguration(),
    // See Layout for writing your own.
    multiDayLayoutStrategy: const MultiDayLayoutStrategy.byDuration(),
    // Null means no cap on the rows of events shown per day.
    maximumNumberOfVerticalEvents: null,
  ),
)
MultiDayBodyConfiguration 
KalenderBody(
  multiDayBodyConfiguration: MultiDayBodyConfiguration(
    showMultiDayEvents: false,
    horizontalPadding: EdgeInsets.only(left: 0, right: 4),
    eventLayoutStrategy: const EventLayoutStrategy.overlap(),
    pageTriggerConfiguration: PageTriggerConfiguration(),
    scrollTriggerConfiguration: ScrollTriggerConfiguration(),
    keepPagesAlive: false,
    // Null lets a tile be as short as its duration. Set a floor, e.g. 24, to
    // keep short events readable.
    minimumTileHeight: null,
    // Null uses the ambient physics. Set your own, e.g. BouncingScrollPhysics().
    scrollPhysics: null,
    pageScrollPhysics: null,
  ),
)
MonthBodyConfiguration 
KalenderBody(
  monthBodyConfiguration: MonthBodyConfiguration(
    tileHeight: 24,
    eventPadding: EdgeInsets.only(left: 0, right: 4, bottom: 2),
    pageTriggerConfiguration: PageTriggerConfiguration(),
    // See Layout for writing your own.
    multiDayLayoutStrategy: const MultiDayLayoutStrategy.byDuration(),
  ),
)
ScheduleBodyConfiguration 
KalenderBody(
  scheduleBodyConfiguration: ScheduleBodyConfiguration(
    emptyDay: EmptyDayBehavior.showOnlyToday,
    leadingWidth: 56,
    pageTriggerConfiguration: PageTriggerConfiguration(),
    scrollTriggerConfiguration: ScrollTriggerConfiguration(),
    // Null uses the ambient physics. Set your own, e.g. BouncingScrollPhysics().
    scrollPhysics: null,
    pageScrollPhysics: null,
  ),
)

Classes

ContinuousScheduleIndexCalculator Views
Calculates page indices and date ranges for a continuous schedule view.
CustomIndexCalculator Views
Calculates page indices and date ranges for a custom multi-day view.
DayIndexCalculator Views
Calculates page indices and date ranges for a single day view.
HorizontalConfiguration Views
The base class for all horizontal views of the calendar.
KalenderBody Views
The calendar body, is a generic widget that creates the relevant widget based on the ViewController.
KalenderHeader Views
KalenderView Views
KalenderViewState Views
MonthBody Views
This widget is used to display a month body.
MonthBodyConfiguration Views
MonthHeader Views
The month header is a simple widget that just displays the day names.
MonthIndexCalculator Views
Calculates page indices and date ranges for a month view.
MonthViewConfiguration Views
MonthWeek Views
A single week in the month view.
MultiDayBody Views
This widget is used to display a multi-day body.
MultiDayBodyConfiguration Views
The configuration used by the MultiDayBody.
MultiDayHeader Views
The multi-day header decides which header to display the:
MultiDayHeaderConfiguration Views
The configuration used by the MultiDayHeader and MonthBody.
MultiDayPage Views
MultiDayViewConfiguration Views
The configuration used by the MultiDayBody and MultiDayHeader.
PageIndexCalculator Views
Calculates page indices and date ranges for paginated calendar views.
PaginatedSchedule Views
A paginated schedule widget that displays events across multiple pages.
PaginatedScheduleIndexCalculator Views
ScheduleBody Views
A widget that displays events in a schedule/list format.
ScheduleBodyConfiguration Views
ScheduleHeader Views
SchedulePositionList Views
A scrollable list widget that displays schedule items with position tracking.
ScheduleViewConfiguration Views
VerticalConfiguration Views
The base class for all vertical views of the calendar.
ViewConfiguration Views
The base class for all ViewConfigurations.
ViewSnapshot Views
A snapshot of what a view was displaying, captured when it is switched away from. Used to restore per-view state on a later switch.
ViewTransitionContext Views
The inputs available when resolving how a view switch or a location change should transfer state.
WeekIndexCalculator Views
Calculates page indices and date ranges for a week view.

Functions

kCarryFocusDate(ViewTransitionContext transition) → FloatingDateTime Views
The "carry the current focus forward" date used by DateTransition.carryFocus.
kDefaultRange() → KalenderDateTimeRange Views
kDefaultToDaily(ViewController old) → FloatingDateTime Views
Carry-focus date when switching to a daily view, derived from old.
kDefaultToMonthly(ViewController old) → FloatingDateTime Views
Carry-focus date when switching to a month view, derived from old.
kDefaultToSchedule(ViewController old) → FloatingDateTime Views
Carry-focus date when switching to a schedule view.
kDefaultToWeekly(ViewController old) → FloatingDateTime Views
Carry-focus date when switching to a weekly (multi-day) view.

Enums

DateTransition Views
How the horizontal date is chosen when switching to a view.
EmptyDayBehavior Views
The default behavior for empty days in the schedule view.
MultiDayViewType Views
ScheduleViewType Views
The type of the schedule view.
ScrollTransition Views
How the vertical scroll position (time-of-day) is chosen when switching to a multi-day view.
ZoomTransition Views
How the zoom (heightPerMinute) is chosen when switching to a multi-day view.

Typedefs

DateResolver = FloatingDateTime Function(ViewTransitionContext transition) Views
Resolves the initial date for the incoming view. Overrides DateTransition.
NowCallback = DateTime Function() Views
A callback that returns the current DateTime representing "now" for the calendar.
ScrollResolver = KalenderTime? Function(ViewTransitionContext transition) Views
Resolves the initial time-of-day for the incoming multi-day view. Overrides ScrollTransition. Return null to use the view's initialTimeOfDay.
ZoomResolver = double? Function(ViewTransitionContext transition) Views
Resolves the initial zoom (heightPerMinute) for the incoming multi-day view. Overrides ZoomTransition. Return null to use initialHeightPerMinute.