Title

The title directive adds a descriptive title to a chart. Similar to scales, axes, and legends, a title can be defined at the top-level of a specification or as part of a group mark.

Title Properties

Properties for specifying a title.

Property Type Description
text String | String[ ] Required. The title text. For versions ≥ 5.7, a string array specifies multiple lines of text.
orient String The orientation of the title and subtitle relative to the chart. One of top (the default), bottom, left, or right.
align String Horizontal text alignment of the title and subtitle. If specified, this value overrides automatic alignment based on the anchor value.
anchor String The anchor position for placing the title and subtitle. One of start, middle (the default), or end. For example, with an orientation of top these anchor positions map to a left-, center-, or right-aligned title.
angle Number Angle in degrees of the title and subtitle text.
baseline String Vertical baseline of the title and subtitle text. One of alphabetic (default), top, middle, bottom, line-top, or line-bottom. The line-top and line-bottom values ≥ 5.10 operate similarly to top and bottom, but are calculated relative to the lineHeight rather than fontSize alone.
color Color Text color of the title text.
dx Number Horizontal offset added to the title and subtitle x-coordinate. ≥ 5.2
dy Number Vertical offset added to the title and subtitle y-coordinate. ≥ 5.2
encode Object Optional mark encodings for custom title styling. In versions ≥ 5.7, supports encoding blocks for group, title, and subtitle. See custom title encodings. The earlier support using a flat encoding block for the title text only is now deprecated; please use nested encoding blocks instead.
font String Font name of the title text.
fontSize Number Font size in pixels of the title text.
fontStyle String Font style of the title text (e.g., normal or italic). ≥ 5.0
fontWeight String | Number Font weight of the title text.
frame String The reference frame for the anchor position, one of "bounds" (the default, to anchor relative to the full bounding box) or "group" (to anchor relative to the group width or height).
interactive Boolean A boolean flag indicating if the title element should respond to input events such as mouse hover. Deprecated: use a custom encode block instead.
limit Number The maximum allowed length in pixels of title and subtitle text.
lineHeight Number Line height in pixels for multi-line title text or title text with "line-top" or "line-bottom" baseline. ≥ 5.7
name String A mark name property to apply to the title text mark. Deprecated: use a custom encode block instead.
offset Number | Value The orthogonal offset in pixels by which to displace the title from its position along the edge of the chart.
style String | String[ ] A mark style property to apply to the title text mark. If not specified, a default style of "group-title" is applied. Deprecated: use a custom encode block instead.
subtitle String | String[ ] Optional subtitle text, placed beneath the primary text. A string array specifies multiple lines of text. ≥ 5.7
subtitleColor Color Text color of the subtitle text. ≥ 5.7
subtitleFont String Font name of the subtitle text. ≥ 5.7
subtitleFontSize Number Font size in pixels of the subtitle text. ≥ 5.7
subtitleFontStyle String Font style of the subtitle text (e.g., normal or italic). ≥ 5.7
subtitleFontWeight String | Number Font weight of the subtitle text. ≥ 5.7
subtitleLineHeight Number Line height in pixels for multi-line subtitle text. ≥ 5.7
subtitlePadding Number Padding in pixels between title and subtitle text. ≥ 5.7
zindex Number The integer z-index indicating the layering of the title group relative to other axis, mark, and legend groups. The default value is 0.

Accessibility Properties ≥ 5.11

Accessibility properties are used to determine ARIA (Accessible Rich Internet Applications) attributes when using Vega to render SVG output.

Property Type Description
aria Boolean A boolean flag (default true) indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG group, removing the title from the ARIA accessibility tree.

Themes and Configuration

To create themes, new default values for many title properties can be set using a config object.

Custom Title Encodings

In addition to the customization parameters above, mark properties can be set for all title elements using the encode parameter. The addressable elements are:

  • group for the title group mark,
  • title for the title text mark, and
  • subtitle for the subtitle text mark.

Each element accepts a set of visual encoding directives grouped into enter, update, exit, etc. objects as described in the Marks documentation. Mark properties can be styled using standard value references.

In addition, each encode block may include a string-valued name property to assign a unique name to the mark set, a boolean-valued interactive property to enable input event handling, and a string-valued (or array-valued) style property to apply default property values. Unless otherwise specified, title elements use a default style of "group-title" and subtitle elements use a default style of "group-subtitle".

The following example shows how to set custom color and font properties for title and subtitle text marks, and enable interactivity for the subtitle text:

"title": {
  "text": "Title Text",
  "subtitle": "Subtitle Text",
  "encode": {
    "title": {
      "enter": {
        "fill": {"value": "purple"}
      }
    },
    "subtitle": {
      "interactive": true,
      "update": {
        "fontStyle": {"value": "italic"}
      },
      "hover": {
        "fontStyle": {"value": "normal"}
      }
    }
  }
}