Calendar

Draws one square cell per day in a calendar grid, each colored by its colorScale value: weekdays down the side and weeks across, one block per year, with month outlines and localized weekday, month, and year labels.

Basic example

Each row’s date (a Date, timestamp, or "YYYY-MM-DD" string) places it in a cell, colored by its colorScale value. Every whole year the data touches gets its own block, stacked, with each month outlined. Days without data are drawn in a neutral fill.

colorScale

Defines the value to be used for a color scale. Can be either an accessor function or a string key to reference in each data point.

date

The day each row falls on: a data key or accessor returning a Date, a millisecond timestamp, or a date string (a bare "YYYY-MM-DD" is read as that local day). Defaults to the row's date, else its time.

cellPadding

Each cell's gap to its neighbors, in pixels.

cellRadius

Each cell's corner radius, in pixels (kept below a third of the cell).

Week start and orientation

orient: "vertical" runs weeks down the page with weekdays across the top, and weekStart: "monday" begins each week on Monday. Without weekStart, weeks begin on the first day of the week in the locale’s region.

orient

The direction weeks run: "horizontal" (weeks left to right, weekdays down the side) or "vertical" (weeks top to bottom, weekdays across the top). Defaults to "horizontal" for year blocks and "vertical" for month blocks, which then read as wall calendars.

horizontalvertical

weekStart

The first day of the week: 0 (Sunday) through 6 (Saturday), or a day name such as "monday". Defaults to the first day of the week in the locale's region (Sunday for "en-US", Monday for "en-GB").

"monday"

Month grid

period: "month" draws each month as its own small wall calendar, arranged in whichever grid gives the largest cells. Titles use "%B %Y", shortening when a block is too narrow.

period

What each block covers: "year" (every whole year the data touches, stacked) or "month" (every whole month, as a grid of small calendars).

yearmonth

orient

horizontalvertical

monthFormat

Formats the month names along year blocks, and the titles of month blocks: a d3-time-format specifier read in the chart's locale, a function of the month's first day, or false for none. Defaults to "%b" along years; month titles use "%B %Y", shortening to fit.

Localized

Weekday, month, and date names come from the locale, and so does the first day of the week: Monday in Spain. weekdayFormat, monthFormat, and yearFormat take any d3-time-format specifier, read in that locale.

weekdayFormat

Formats the weekday names: a d3-time-format specifier read in the chart's locale, a function of a date on that weekday, or false for none. Defaults to "%a"; names wider than a cell shorten to their first letter.

monthFormat

yearFormat

Formats the year beside each year block: a d3-time-format specifier, a function of the year's first day, or false for none. Defaults to "%Y".

Custom styling

Square cells with wider gaps, a fixed emptyFill, a four-step green colorScaleConfig, and the month outlines and weekday names turned off.

cellPadding

Each cell's gap to its neighbors, in pixels.

cellRadius

Each cell's corner radius, in pixels (kept below a third of the cell).

emptyFill

The fill of days without a value: days missing from the data, and rows whose colorScale value isn't a number. Defaults to the theme's colorScale.missing when it sets one, else a faint tint of the chart's text color, legible on light and dark backgrounds.

monthOutline

Whether to outline each month inside year blocks (see monthOutlineConfig).

weekdayFormat

false

Small multiples

facet draws one calendar per repo. The panels share one date range, so a day sits in the same cell in each, and one color scale.

Configuration

import {Calendar} from "@d3plus/core";

Extends Viz.

Filter 42 config keys

activefalse | function

The active callback function for highlighting shapes.

calendarLabelConfigobjectDefault {}

Styles the weekday, month, and year labels: fontColor, fontFamily, fontSize (default 11), and fontWeight. The color defaults to the chart's text color, softened toward the background.

cellPaddingnumberDefault 2

Each cell's gap to its neighbors, in pixels.

cellRadiusnumberDefault 2

Each cell's corner radius, in pixels (kept below a third of the cell).

classNamestring | array.<string> | undefined

CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.

colorDefaultscolordefaultsconfig

Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.

colorScalestring | false | functionDefault "value"

Defines the value to be used for a color scale. Can be either an accessor function or a string key to reference in each data point.

configd3plusconfig

Methods that correspond to the key/value pairs and returns this class.

datastring | array.<datapoint> | object

The primary data array used to draw the visualization. The value passed should be an Array of objects or a String representing a filepath or URL to be loaded. The following filetypes are supported: csv, tsv, txt, and json.

If your data URL needs specific headers to be set, an Object with a "url" and "headers" (or any other fetch request option) may also be passed. An Object with any other key is a data row, not a request.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final array of obejcts to be used as the primary data array. For example, some JSON APIs return the headers split from the data values to save bandwidth. These would need be joined using a custom formatter.

If you would like to specify certain configuration options based on the yet-to-be-loaded data, you can also return a full config object from the data formatter (including the new data array as a key in the object).

To re-fetch a URL on an interval and redraw when its data changes, set dataPollingInterval; each poll runs the same formatter.

Defaults to an empty array ([]).

datestring | functionDefault defaultCalendarDate

emptyFillstring

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

facetConfigfacetconfig

Configuration for small multiples (see facet), merged into the current config: - columns / rows: the grid's shape. Chosen by default to make the panels as large as the chart's shape allows. - padding: the space between panels, in pixels (default 20). - sort: panel order — "ascending" (default), "descending", "data" (first appearance), a comparator over facet values, or an Array of values. - scales: "shared" (default) gives every panel of a chart with axes the same x/y domains; "independent" fits each panel to its own rows. Funnel defaults to "independent" (each panel sized to its own widest stage); "shared" sizes every panel against the widest stage across all panels. PolarArea and RadialBar default to "independent" (each panel's rings and ticks fit its own values); "shared" gives every panel the same value domain. - axes: with shared scales, "outer" (default) labels the axes only along the grid's left and bottom edges; "all" labels every panel. An object sets each axis on its own, as in {x: "all", y: "outer"}: every panel labels its x axis, only the left column labels its y axis, and the panels' plot areas line up. BumpChart defaults to "all", and Marimekko labels its categories on every panel and its 0–100% share axis only along the outer edge, even with independent scales. - title: a (value, data) => string function for each panel's title, or false to hide panel titles. - titleConfig: TextBox config for the panel titles (fontSize, fontWeight, fontColor, textAnchor, padding, …).

fontFamilystring | array.<string>

The font family used throughout the visualization.

groupBystring | function | array.<string | function>

Defines the mapping between data and shape. The value can be a String matching a key in each data point (default is "id"), or an accessor Function that returns a unique value for each data point. Additionally, an Array of these values may be provided if the visualization supports nested hierarchies.

highlightfalse | function

Persistently emphasizes the data points matching the given predicate: the matching marks keep their color while every other mark is de-emphasized to a neutral gray (the "emphasis" form — highlight one series, gray the rest). Unlike hover/active (transient, opacity-based), highlight is a standing state that survives pointer movement. Pass false to clear it.

hoverfalse | function

The hover callback function for highlighting shapes on mouseover.

labelstring | false | array.<string> | accessorfnDefault function

Accessor function, or a constant string applied to every data point's label (unlike value/nodeId/etc., a string here is not treated as a per-datum object key — pass a function for that).

legendboolean | functionDefault function

Whether to display the legend. By default, the legend shows when it has more than one entry and each entry stands for a single group (or two groups at most), or when the entries are colored by a category that isn't a groupBy level (see color), in which case each entry is labelled by its category. Pass false to hide it, true to always show it, or a (config, data) => boolean function to decide.

localestring | object

The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.

monthFormatstring | false | function

monthOutlinebooleanDefault true

Whether to outline each month inside year blocks (see monthOutlineConfig).

monthOutlineConfigobjectDefault {}

Styles the month outlines: stroke (defaults to a tint of the chart's text color), strokeWidth (default 1), and strokeDasharray.

onstring

Event listener for the specified event typenames. Mirrors the core d3-selection behavior.

orient"horizontal" | "vertical"

parentunknown

Parent config used by the wrapper.

period"year" | "month"Default "year"

What each block covers: "year" (every whole year the data touches, stacked) or "month" (every whole month, as a grid of small calendars).

renderfunction

Draws the visualization given the specified configuration.

rendererboolean | "svg" | "canvas"

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

selectstring | htmlelement

The SVG container element as a d3 selector or DOM element. Defaults to undefined.

shapeConfigd3plusconfigDefault {hoverOpacity: 1}

Configuration object with key/value pairs applied as method calls on each shape.

Hovering a day outlines it without fading the other days (hoverOpacity: 1); hovering a colorScale bucket still fades the days outside it.

thresholdnumber | function

The threshold value for bucketing small data points together, as a share of the total. On a stacked Plot, the series whose summed value across every position is under that share of the whole chart's total merge into one series, stacked on top. A bucket needs at least two items, and its tooltips list them. Off (0) by default on Plot charts.

thresholdKeystring | function

Accessor for the value used in the threshold algorithm. A stacked Plot defaults to its stacked value.

timestring | false | function

Accessor function or string key for the time dimension of each data point.

timelineDefaultstring | date | array.<string | date>

The starting time or range for the timeline. Can be a single Date/String, or an Array of 2 values representing the min and max.

tooltipConfigtooltipconfig

Adds a "Value" row with the day's colorScale value to the tooltip.

totalstring | boolean | function

Accessor function or string key for the total value displayed in the visualization.

translatefunction

Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.

weekStartstring | number

weekdayFormatstring | false | function

yearFormatstring | false | function

Formats the year beside each year block: a d3-time-format specifier, a function of the year's first day, or false for none. Defaults to "%Y".

zoombooleanDefault false

Whether the chart zooms and pans. Off by default: every day is already in view.