Calendar

Calendars are used for date selection within a defined time period.

Calendar

Maven Central Class reference Source code

Labeled

Day Night
Labeled Calendar2 component Labeled Calendar2 component - dark mode

Icon as labeled

Day Night
Day icon as labeled Calendar2 component Day icon labeled Calendar2 component - dark mode

Month

Day Night
Month Calendar2 component Month Calendar2 component - dark mode

Range

Day Night
Range Calendar2 component Range Calendar2 component - dark mode

Installation

Backpack Android is available through Maven Central. Check the main Readme for a complete installation guide.

Usage

BpkCalendar uses coroutines under the hood. Since it designed with coroutines, the API is designed primarily for Kotlin language and may not be interoperable with Java. To use the API, make sure kotlinx-coroutines is included to your project.

BpkCalendar is designed as a state machine. All the information it contains is available as a state in the StateFlow. Each method of the public API and some of the user interactions will change its state and emit it.

The Calendar component can be used in both XML and Kotlin, but requires the basic setup to be done in Kotlin. Both single and range selection are supported.

Example of a calendar declaration in XML

NOTE: Note that the package name of new Calendar has been changed to net.skyscanner.backpack.calendar2.

<net.skyscanner.backpack.calendar2.BpkCalendar
    android:id="@+id/bpkCalendar"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:nestedScrollingEnabled="true"/>

Example of a declaration in Kotlin

import net.skyscanner.backpack.calendar2.BpkCalendar

BpkCalendar(context)

Once you've declared the calendar, you need to setup it like following:

calendar.setParams(
  CalendarParams(
    range = LocalDate.of(2019, 1, 2)..LocalDate.of(2019, 12, 31), // start and end dates in the range
    selectionMode = CalendarParams.SelectionMode.Single, // selection mode - can be Single, Dates, Months or Disabled
  )
)

Now the component is ready. You can listen for the selection change using its state:

calendar
  .state
  .map { it.selection }
  .onEach { selection ->
    when (selection) {
      is CalendarSelection.None -> showToast("No date is selected")
      is CalendarSelection.Single -> showToast("${selection.date} is selected")
      is CalendarSelection.Dates -> showToast("${selection.start} to {${selection.end} is selected")
      is CalendarSelection.Month -> showToast("${selection.month} is selected")
    }
  }
  .launchIn(myCoroutineScope)

Advanced dates customisation

You can attach some of the information to each date displayed in calendar. This information will update its appearance and behaviour.

In order to do this, specify cellInfo parameters like shown here:

calendar.setParams(
  CalendarParams(
    range = range,
    selectionMode = selectionMode,
    cellsInfo = mapOf(
      LocalDate.of(2019, 1, 2) to CellInfo(
        disabled = true, // marks date as disabled
        status = CellStatus.Positive, // adds green colour to cell, you can use Neutral, Negative, Empty and null as well
        label = CellLabel.Text("£30"), // adds label below the date
      ),
    )
  )
)

You can also use icons as the cell info:

controller.setParams(
  CalendarParams(
    range = range,
    selectionMode = selectionMode,
    cellsInfo = mapOf(
      LocalDate.of(2019, 1, 2) to CellInfo(
        disabled = true, // marks date as disabled
        status = CellStatus.Positive, // adds green colour to cell, you can use Neutral, Negative, Empty and null as well
        label = CellLabel.Icon(resId = R.drawable.bpk_search_sm, tint = R.color.bpkCoreAccent), // adds icon below the date
      ),
    )
  )
)

Theme Props

  • calendarDateSelectedBackgroundColor
  • calendarDateSelectedRangeBackgroundColor
  • calendarDateSelectedTextColor
  • calendarDateSelectedSameDayBackgroundColor

Styles can be changed globally through bpkCalendarStyle. Check theming for more information.