README.md

CalendarView

A highly customizable calendar library for Android, powered by RecyclerView.

With this library, your calendar will look however you want it to.

Features

• Single or range selection - The library provides the calendar logic which enables you to implement the view whichever way you like.
• Boundary dates - limit the calendar date range.
• Custom date view - make your day cells look however you want, with any functionality you want.
• Custom calendar view - make your calendar look however you want, with whatever functionality you want.
• Pick any day to be the first day of the week.
• Horizontal or vertical scrolling mode.
• Add headers/footers of any kind on each month.
• Easily scroll to any date or month view using the date.
• Use all RecyclerView customisations(decorators etc) since the CalendarView entends from RecyclerView.
• Design your calendar however you want. The library provides the logic, you provide the views.

Sample project

It's very important to check out the sample app. Most techniques that you would want to implement are already implemented in the examples.

Get the sample app here

View the sample app's source code here

Usage

Step 1

The library uses java.time classes via ThreeTenABP for backward compatibility since these classes were added in Java 8. Therefore, you need to initialize ThreeTenABP in your application class.

class SampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AndroidThreeTen.init(this)
    }
}

Add CalendarView to your XML like any other view.

<com.kizitonwose.calendarview.CalendarView
    android:id="@+id/calendarView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:cv_dayViewResource="@layout/calendar_day_layout" />

See all available attributes.

Step 2

Create your day view resource in res/layout/calendar_day_layout.xml.

<TextView
    android:id="@+id/calendarDayText"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:gravity="center"
    android:textSize="16sp"
    tools:text="22" />

Create your view container which acts as a view holder for each date cell. The view passed in here is the inflated day view resource which you provided.

class DayViewContainer(view: View) : ViewContainer(view) {
    val textView = view.calendarDayText
    
    // Without the kotlin android extensions plugin
    // val textView = view.findViewById<TextView>(R.id.calendarDayText)
}

Provide a DayBinder for the CalendarView using your DayViewContainer type.

calendarView.dayBinder = object : DayBinder<DayViewContainer> {
    // Called only when a new container is needed.
    override fun create(view: View) = DayViewContainer(view)
    
    // Called every time we need to reuse a container.
    override fun bind(container: DayViewContainer, day: CalendarDay) {
        container.textView.text = day.date.dayOfMonth.toString()
    }
}

Step 3

Setup the desired dates in your Fragment or Activity:

val currentMonth = YearMonth.now()
val firstMonth = currentMonth.minusMonths(10)
val lastMonth = currentMonth.plusMonths(10)
val firstDayOfWeek = WeekFields.of(Locale.getDefault()).firstDayOfWeek
calendarView.setup(firstMonth, lastMonth, firstDayOfWeek)
calendarView.scrollToMonth(currentMonth)

And that's all you need for a simple usage!

To add a header or footer to each month, the procedure is the same. Just provide your monthHeaderResource or monthFooterResource attribute, then set the monthHeaderBinder or monthFooterBinder property of the CalendarView. For more complex usages, please see the sample project.

In the example above, we get the first day of the week from the current locale, however, we can use a specific day regardless of locale by passing in the value DayOfWeek.SUNDAY, DayOfWeek.MONDAY etc

Attributes

XML (All prefixed cv_ for clarity)

• dayViewResource: The xml resource that is inflated and used as the day cell view. This must be provided.

• monthHeaderResource: The xml resource is inflated and used as a header for every month.

• monthFooterResource: The xml resource is inflated and used as a footer for every month.

• orientation: The calendar orientation, can be horizontal or vertical. Default is vertical.

• scrollMode: The scrolling behavior of the calendar. Can be paged or continuous. If paged, the calendar will snap to the nearest month after a scroll or swipe action. Default value is continuous.

• outDateStyle: This determines how outDates are generated for you. If endOfRow , the calendar will generate outDates until it reaches the first end of a row. This means that if a month has 6 rows, it will display 6 rows and if a month has 5 rows, it will display 5 rows. However, if this value is set to endOfGrid, the calendar will generate outDates until it reaches the end of a 6 x 7 grid. This means that all months will have 6 rows.

If you are wondering what outDates and inDates mean, let's use the screenshot below as an example.

In the image, the dates with the green annotation are inDates while those with the red annotation are outDates. You can check for this when binding your calendar. To achieve the exact effect on the image, we do this:

calendarView.dayBinder = object : DayBinder<DayViewContainer> {
    override fun create(view: View) = DayViewContainer(view)
    override fun bind(container: DayViewContainer, day: CalendarDay) {
        container.textView.text = day.date.dayOfMonth.toString()
        if (day.owner == DayOwner.THIS_MONTH) {
            container.textView.setTextColor(Color.WHITE)
        } else {
            container.textView.setTextColor(Color.GRAY)
        }
    }
}

inDates have their owner property set to DayOwner.PREVIOUS_MONTH

outDates have their owner property set to DayOwner.NEXT_MONTH

Dates which belong to the month have their owner property set to DayOwner.THIS_MONTH as seen in the code snippet above.

Properties

• monthScrollListener: Called when the calendar scrolls to a new month. Mostly beneficial if scrollMode is paged.

• dayBinder: An instance of DayBinder for managing day cell views.

• monthHeaderBinder: An instance of MonthHeaderFooterBinder for managing header views.

• monthFooterBinder: An instance of MonthHeaderFooterBinder for managing footer views.

• dayWidth: The width, in pixels for each day cell view.

• dayHeight: The height, in pixels for each day cell view.

Note that setting either dayWidth or dayHeight to CalendarView.DAY_SIZE_SQUARE makes the day cells have equal width and height which is basically the width of the calendar divided by 7. DAY_SIZE_SQUARE is the default day width and height value.

Methods

• scrollToDate(date: LocalDate): Scroll to a specific date on the calendar.

• scrollToMonth(month: YearMonth): Scroll to a month on the calendar.

• notifyDateChanged(date: LocalDate): Reload the view for the specified date.

• notifyMonthChanged(month: YearMonth): Reload the header, body and footer views for the specified month.

• notifyCalendarChanged(): Reload the entire calendar.

There's no need listing all available methods or repeating the documentation here. Please see the CalendarView class for all properties and methods available with proper documentation.

Made a cool calendar with this library? Share an image here.

Setup

Gradle

Add the JitPack repository to your project level build.gradle:

allprojects {
 repositories {
    google()
    jcenter()
    maven { url "https://jitpack.io" }
 }
}

Add this to your app build.gradle:

dependencies {
	implementation 'com.github.kizitonwose:CalendarView:<latest-version>'
}

Note: <latest-version> value can be found on the JitPack badge above the preview images.

Contributing

Found a bug? feel free to fix it and send a pull request or open an issue.

Inspiration

CalendarView was inspired by the iOS library JTAppleCalendar. I used JTAppleCalendar in an iOS project but couldn't find anything as customizable on Android so I built this. You'll find some similar terms like endOfRow, endOfGrid, DayOwner etc.

License

CalendarView is distributed under the MIT license. See LICENSE for details.