Skip to main content

Calendar pattern usage.

Calendar Patterns

Calendar patterns are a collection of time related rules and provide a way to specify complex date patterns such as specific days in a week, year, and even time intervals. For example:

// The fifth of February.
{ month: 2, day: 5 }

See the calendarPattern API for a complete list of available filters.

Filter Settings

The month filter is used below to demonstrate values all filters accept.

Value

// Matches February.
{ month: 2 }

Date

// This is equivalent to the value 2 because
// only the month part extracted from it.
{ month: "2/1/20" }

Multiple Values

// February and May.
{ month: [2, 5] }

Range

// February , March, April, and May.
{ month_range: [2, 5] }

Asterisk

// Means every month and puts the pattern into interval mode.
{ month: "*" }

Function

// A custom function to match months of given dates.
{
  month: function(date) {
    /*return true if date matches*/
  }
}

In addition to filters, there are also two properties: every and inclusive that are described in more detail below.

Usage

The API for these patterns is robust and easy to read. For example, a pattern that covers weekends can be defined as:

{ weekday: [0, 6] }

Multiple filters can be used to restrict the pattern range. The addition of the month filter changes the meaning to weekends in January.

{ weekday: [0, 6], month: 1 }

Alternatively, extra filters can expand the pattern by adding the inclusive property. The pattern below describes all weekends and all days in January.

{ weekday: [0, 6], month: 1, inclusive: false }

A more complex example is defining a pattern that marks the first Sunday of every month:

{ day_range: [1, 7], weekday: 6 }

If a matching pattern is too difficult to define, a custom function can be used as well:

{
  date: function(date) {
    /*Match date*/
  }
}

Intervals

An interval pattern that refers to months (every month) can be specified like so:

{ month: "*" }

This interval pattern covers 100% of any time span but is useful with calendar heatmaps to outline specific date groupings.

{ month: "*", every: 3 }

Rules

Filters with '*' value can be mixed with other filters, but only one filter can have a '*' value.