This website is for Vega-Lite v2. Go to the main Vega-Lite homepage for the latest release.

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 config (config: {header: {...}}).

Documentation Overview

Header Properties

// Single View Specification
{
  "data": ... ,
  "mark": ... ,
  "encoding": {
    "row": {
      "field": ...,
      "type": ...,
      "header": {                // Header
        ...
      },
      ...
    },
    "x": ...,
    "y": ...,
    ...
  }
}

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

General

Property Type Description
format String

The formatting pattern for labels. This is D3’s number format pattern for quantitative fields and D3’s time format pattern for time field.

See the format documentation for more information.

Default value: derived from numberFormat config for quantitative fields and from timeFormat config for temporal fields.
title String | 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
labelAngle Number

The rotation angle of the header labels.

Default value: 0.
labelColor String

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

The font of the header label.
labelFontSize Number

The font size of the header label, in pixels.
labelLimit Number

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

Title

Property Type Description
titleAnchor 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.

Default value: "middle" for single and layered views. "start" for other composite views.

Note: For now, anchor is only customizable only for single and layered views. For other composite views, anchor is always "start".
titleAngle Number

The rotation angle of the header title.

Default value: 0.
titleBaseline TextBaseline

Vertical text baseline for the header title. One of "top", "bottom", "middle".

Default value: "middle"
titleColor String

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

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

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

Font size of the header title.
titleLimit Number

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

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
      ...
    }
    ...
  }
}

The header property of the top-level config object sets the default properties for all headers. If header properties are set in row- or column-field definitions, these config values will be overridden.

The header config can contain any header properties.