Calendar Patterns

Chart Tutorials  

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.