Header

Edit this page

Headers provide a title and labels for faceted plots. A header’s title describes the field that is used to facet the plot, while a header’s labels describe that field’s value for each subplot.

By default, Vega-Lite automatically creates headers with default properties for row and column channels of a faceted view. User can set the header property of row- or column-field definition to an object to customize header properties.

In addition to the header property of a row- or column-field definition, users can also set default header properties for all headers with the configuration object’s (config) header configuration (config: {header: {...}}).

Documentation Overview

Header Properties

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    "row": {
      "field": ...,
      "type": ...,
      "header": {...}, // Header
      ...
    },
    "x": ...,
    "y": ...,
    ...
  }
}

// A Facet Specification
{
  ...,
  "facet": {
    "row/column": {
      "field": ...,
      "type": ...,
      "header": {...}, // Header
      ...
    },
    ...
  },
  "spec": ...
}

To customize header, a header definiton in row- or column-field definitions can contain the following groups of properties:

General

Property Type Description
title Text | Null

A title for the field. If null, the title will be removed.

Default value: derived from the field’s name and transformation function (aggregate, bin and timeUnit). If the field has an aggregate function, the function is displayed as part of the title (e.g., "Sum of Profit"). If the field is binned or has a time unit applied, the applied function is shown in parentheses (e.g., "Profit (binned)", "Transaction Date (year-month)"). Otherwise, the title is simply the field name.

Notes:

1) You can customize the default field title format by providing the fieldTitle property in the config or fieldTitle function via the compile function’s options.

2) If both field definition’s title and axis, header, or legend title are defined, axis/header/legend title will be used.

See also: You may also use guide-title and guide-label style configs to customize common styles for axis, legend, and header labels and titles.

Labels

Property Type Description
format Format

The text format specifier for formatting number and date/time in labels of guides (axes, legends, headers) and text marks.

If the format type is "number" (e.g., for quantitative fields), this is a D3’s number format pattern string.

If the format type is "time" (e.g., for temporal fields), this is either: a) D3’s time format pattern if you desire to set a static time format.

b) dynamic time format specifier object if you desire to set a dynamic time format that uses different formats depending on the granularity of the input date (e.g., if the date lies on a year, month, date, hour, etc. boundary).

When used with a custom formatType, this value will be passed as format alongside datum.value to the registered function.

Default value: Derived from numberFormat config for number format and from timeFormat config for time format.
formatType String

The format type for labels. One of "number", "time", or a registered custom format type.

Default value:

  • "time" for temporal fields and ordinal and nominal fields with timeUnit.
  • "number" for quantitative fields as well as ordinal and nominal fields without timeUnit.
labelAlign String | ExprRef

Horizontal text alignment of header labels. One of "left", "center", or "right".
labelAnchor Null | String

The anchor position for placing the labels. One of "start", "middle", or "end". For example, with a label orientation of top these anchor positions map to a left-, center-, or right-aligned label.
labelAngle Number

The rotation angle of the header labels.

Default value: 0 for column header, -90 for row header.
labelBaseline String | ExprRef

The vertical text baseline for the header labels. One of "alphabetic" (default), "top", "middle", "bottom", "line-top", or "line-bottom". The "line-top" and "line-bottom" values operate similarly to "top" and "bottom", but are calculated relative to the titleLineHeight rather than titleFontSize alone.
labelColor Color | ExprRef

The color of the header label, can be in hex color code or regular color name.
labelExpr String

Vega expression for customizing labels.

Note: The label text and value can be assessed via the label and value properties of the header’s backing datum object.
labelFont String | ExprRef

The font of the header label.
labelFontSize Number | ExprRef

The font size of the header label, in pixels.
labelFontStyle String | ExprRef

The font style of the header label.
labelFontWeight String | Number | ExprRef

The font weight of the header label.
labelLimit Number | ExprRef

The maximum length of the header label in pixels. The text value will be automatically truncated if the rendered size exceeds the limit.

Default value: 0, indicating no limit
labelLineHeight Number | ExprRef

Line height in pixels for multi-line header labels or title text with "line-top" or "line-bottom" baseline.
labelOrient String

The orientation of the header label. One of "top", "bottom", "left" or "right".
labelPadding Number | ExprRef

The padding, in pixel, between facet header’s label and the plot.

Default value: 10

Title

Property Type Description
titleAlign String | ExprRef

Horizontal text alignment (to the anchor) of header titles.
titleAnchor Null | String

The anchor position for placing the title. One of "start", "middle", or "end". For example, with an orientation of top these anchor positions map to a left-, center-, or right-aligned title.
titleAngle Number

The rotation angle of the header title.

Default value: 0.
titleBaseline String | ExprRef

The vertical text baseline for the header title. One of "alphabetic" (default), "top", "middle", "bottom", "line-top", or "line-bottom". The "line-top" and "line-bottom" values operate similarly to "top" and "bottom", but are calculated relative to the titleLineHeight rather than titleFontSize alone.

Default value: "middle"
titleColor Color | ExprRef

Color of the header title, can be in hex color code or regular color name.
titleFont String | ExprRef

Font of the header title. (e.g., "Helvetica Neue").
titleFontWeight String | Number | ExprRef

Font weight of the header title. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
titleFontSize Number | ExprRef

Font size of the header title.
titleFontStyle String | ExprRef

The font style of the header title.
titleFontWeight String | Number | ExprRef

Font weight of the header title. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
titleLimit Number | ExprRef

The maximum length of the header title in pixels. The text value will be automatically truncated if the rendered size exceeds the limit.

Default value: 0, indicating no limit
titleLineHeight Number | ExprRef

Line height in pixels for multi-line header title text or title text with "line-top" or "line-bottom" baseline.
titleOrient String

The orientation of the header title. One of "top", "bottom", "left" or "right".
titlePadding Number | ExprRef

The padding, in pixel, between facet header’s title and the label.

Default value: 10

Example

This example uses header properties to change the font size of this faceted plot’s title and labels.

Header Config

// Top-level View Specification
{
  ...
  "config": {
    "header": {...},               // Header
    "headerRow": {...},
    "headerColumn": {...},
    "headerFacet": {...},
    ...
  }
}

The header property of the top-level config object sets the default properties for all headers. If header properties are set in row-, column-, or facet-field definitions, these configuration values will be overridden. Additional property blocks can target more specific header types based on types of facet channels ("headerRow", "headerColumn", "headerFacet").

The header configuration can contain any header properties.