Titles

View titles label complete views, tracks, and composed layouts. A title can be given as a string shorthand or as a title object:

String title shorthand

{
  "title": "Copy number"
}

Title object

{
  "title": {
    "text": "Copy number",
    "subtitle": "Segment mean",
    "orient": "top",
    "anchor": "start"
  }
}

Example

{
  "description": "Basic title and subtitle example.",

  "title": {
    "text": "Cosine wave",
    "subtitle": "A basic title with secondary text",
    "anchor": "start"
  },

  "data": { "url": "data/sincos.csv" },

  "mark": "point",

  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "cos", "type": "quantitative" }
  }
}

Placement

The orient property controls the side of the plot area where the title is placed. Supported orientations are:

• top
• right
• bottom
• left
• none

The anchor property controls the title position along that side. For example, with orient: "top", anchor: "start" places the title near the left edge, "middle" centers it, and "end" places it near the right edge.

Reserved and overlay titles

By default, titles reserve layout space on the side indicated by orient. Reserved titles are placed outside axes, legends, and other guide space on the same side.

Set reserve to false when the title should render without affecting layout. This enables overlay-style layouts where the title can overlap nearby content or the plot area.

The frame property controls the reference frame used for the title anchor:

• "group" anchors the title along the plot area.
• "bounds" anchors the title along the full reserved area of the view.

Overlay titles commonly use reserve: false and frame: "group" so that the title is positioned relative to the plot area but does not reserve extra space.

Subtitles

Use subtitle to add secondary title text. Subtitles share the same orientation and anchor as the main title. subtitlePadding controls the spacing between the main title and subtitle.

Subtitle styling can be configured separately with properties such as subtitleColor, subtitleFontSize, and subtitleFontWeight.

The default subtitle text style comes from the built-in "group-subtitle" style. Override config.style["group-subtitle"] to change subtitle defaults without changing main title text.

Styling

Title defaults come from config.title and from named styles in config.style. If title.style is omitted, GenomeSpy applies the built-in "group-title" style. See Config and Themes for more about configuration scopes and named styles.

GenomeSpy includes built-in title styles for common layout patterns:

• "group-title" for ordinary view and group titles
• "track-title" for compact track labels
• "overlay-title" for titles drawn over the plot area

{
  "description": "Built-in title style examples.",

  "data": { "url": "data/sincos.csv" },

  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "cos", "type": "quantitative", "axis": null }
  },

  "vconcat": [
    {
      "title": { "text": "Group title (the default)", "style": "group-title" },
      "mark": "point"
    },
    {
      "title": { "text": "Track title", "style": "track-title" },
      "mark": "point"
    },
    {
      "title": { "text": "Overlay title", "style": "overlay-title" },
      "mark": "point"
    },
    {
      "title": { "text": "Custom title", "style": "custom-title" },
      "mark": "point"
    }
  ],

  "config": {
    "style": {
      "custom-title": {
        "fontSize": 18,
        "fontWeight": "bold",
        "color": "#4a90e2"
      }
    },
    "view": { "stroke": "#d0d0d0", "strokeWidth": 1 }
  },

  "resolve": { "scale": { "x": "shared" }, "axis": { "x": "shared" } }
}

Named styles can be referenced with title.style:

{
  "title": {
    "text": "Custom title",
    "style": "custom-title"
  },
  "config": {
    "style": {
      "custom-title": {
        "fontSize": 18,
        "fontWeight": "bold",
        "color": "#4a90e2"
      }
    }
  }
}

Use config.title for defaults that apply to all titles in a configuration scope:

{
  "config": {
    "title": {
      "fontSize": 13,
      "subtitleFontSize": 11,
      "subtitlePadding": 4
    }
  }
}

Properties

align

Type: "left" | "center" | "right"

Horizontal text alignment for title text. One of "left", "center", or "right".

anchor

Type: None | start | middle | end

The anchor position for placing the title and subtitle text. 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.

angle

Type: number | ExprRef

Angle in degrees of title and subtitle text.

baseline

Type: "top" | "middle" | "bottom" | "alphabetic" | "baseline"

Vertical text baseline for title and subtitle text. One of "alphabetic" (default), "top", "middle", or "bottom".

color

Type: string | ExprRef

Text color for title text.

dx

Type: number

Delta offset for title and subtitle text x-coordinate.

dy

Type: number

Delta offset for title and subtitle text y-coordinate.

font

Type: string

Font name for title text.

fontSize

Type: number | ExprRef

Font size in pixels for title text.

fontStyle

Type: "normal" | "italic"

Font style for title text.

fontWeight

Type: number | "thin" | "light" | "regular" | "normal" | "medium" | "bold" | "black"

Font weight for title text. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, ..., 900 where "normal" = 400 and "bold" = 700).

frame

Type: "bounds" | "group"

The reference frame for the title anchor. "group" anchors the title along the plot area. "bounds" anchors the title along the full bounds, including axes, legends, and other reserved space.

Default value: "group"

offset

Type: number

The orthogonal offset in pixels by which to displace the title group from its position along the edge of the chart.

orient

Type: "none" | "left" | "right" | "top" | "bottom"

Default title orientation ("none", "top", "bottom", "left", or "right")

reserve

Type: boolean

Whether the title reserves layout space outside the plot area. Reserved titles are placed outside axes, legends, and other guide space on the same side.

Setting this to false lets the title render without affecting layout, enabling wilder layouts where titles may overlap nearby content.

Default value: true

style

Type: string | string[]

A mark style property to apply to the title text mark. If not specified, a default style of "group-title" is applied.

subtitle

Type: string | ExprRef

The subtitle text.

subtitleColor

Type: string | ExprRef

Text color for subtitle text.

subtitleFont

Type: string

Font name for subtitle text.

subtitleFontSize

Type: number | ExprRef

Font size in pixels for subtitle text.

subtitleFontStyle

Type: "normal" | "italic"

Font style for subtitle text.

subtitleFontWeight

Type: number | "thin" | "light" | "regular" | "normal" | "medium" | "bold" | "black"

Font weight for subtitle text. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, ..., 900 where "normal" = 400 and "bold" = 700).

subtitlePadding

Type: number

Padding in pixels between title and subtitle text.

Default value: 3

text Required

Type: string | ExprRef

The title text.

zindex

Type: number

Z-order of the title relative to the view content.

Values greater than 0 render after the view marks. Values less than or equal to 0 render before the marks.

Default value: 1

Config Properties

align

Type: "left" | "center" | "right"

Horizontal text alignment for title text. One of "left", "center", or "right".

anchor

Type: None | start | middle | end

The anchor position for placing the title and subtitle text. 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.

angle

Type: number | ExprRef

Angle in degrees of title and subtitle text.

baseline

Type: "top" | "middle" | "bottom" | "alphabetic" | "baseline"

Vertical text baseline for title and subtitle text. One of "alphabetic" (default), "top", "middle", or "bottom".

color

Type: string | ExprRef

Text color for title text.

dx

Type: number

Delta offset for title and subtitle text x-coordinate.

dy

Type: number

Delta offset for title and subtitle text y-coordinate.

font

Type: string

Font name for title text.

fontSize

Type: number | ExprRef

Font size in pixels for title text.

fontStyle

Type: "normal" | "italic"

Font style for title text.

fontWeight

Type: number | "thin" | "light" | "regular" | "normal" | "medium" | "bold" | "black"

Font weight for title text. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, ..., 900 where "normal" = 400 and "bold" = 700).

frame

Type: "bounds" | "group"

The reference frame for the title anchor. "group" anchors the title along the plot area. "bounds" anchors the title along the full bounds, including axes, legends, and other reserved space.

Default value: "group"

offset

Type: number

The orthogonal offset in pixels by which to displace the title group from its position along the edge of the chart.

orient

Type: "none" | "left" | "right" | "top" | "bottom"

Default title orientation ("none", "top", "bottom", "left", or "right")

reserve

Type: boolean

Whether the title reserves layout space outside the plot area. Reserved titles are placed outside axes, legends, and other guide space on the same side.

Setting this to false lets the title render without affecting layout, enabling wilder layouts where titles may overlap nearby content.

Default value: true

style

Type: string | string[]

A mark style property to apply to the title text mark. If not specified, a default style of "group-title" is applied.

subtitle

Type: string | ExprRef

The subtitle text.

subtitleColor

Type: string | ExprRef

Text color for subtitle text.

subtitleFont

Type: string

Font name for subtitle text.

subtitleFontSize

Type: number | ExprRef

Font size in pixels for subtitle text.

subtitleFontStyle

Type: "normal" | "italic"

Font style for subtitle text.

subtitleFontWeight

Type: number | "thin" | "light" | "regular" | "normal" | "medium" | "bold" | "black"

Font weight for subtitle text. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, ..., 900 where "normal" = 400 and "bold" = 700).

subtitlePadding

Type: number

Padding in pixels between title and subtitle text.

Default value: 3

zindex

Type: number

Z-order of the title relative to the view content.

Values greater than 0 render after the view marks. Values less than or equal to 0 render before the marks.

Default value: 1