How to Add and Customize Titles in Vega-Lite Charts?
Want to make your Vega-Lite charts more informative and appealing? Adding a title can help! In this guide, we'll walk you through how to add a title to your charts and customize it to fit your needs.
Why Add a Title?
A title gives your chart context and helps viewers quickly understand what the data is about. Imagine flipping through a document or a dashboard with multiple charts—having titles makes navigation and comprehension much easier.
Adding a Basic Title
You can use the title property in your view specification. It can be as simple as a string. Let's start with a basic example:
Example: A Simple Bar Chart with a Title
{
"title": "A Simple Bar Chart",
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}Here, the title "A Simple Bar Chart" will be displayed at the top of the chart.
Customizing Your Chart Title
Now that you've got the basic title down, let's explore how you can customize it. You can do more than just add text; you can adjust its appearance and position to match your design needs.
Title Properties Object
The title property can also be an object that defines various properties. Here are some of the things you can customize:
| Property | Type | Description |
|---|---|---|
| text | Text | ExprRef | Required. The title text. |
| align | String | Horizontal text alignment for title text. One of "left", "center", or "right". |
| anchor | 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. Default value: "middle" for single (opens in a new tab) and layered (opens in a new tab) views. "start" for other composite views. Note: For now (opens in a new tab), anchor is only customizable only for single (opens in a new tab) and layered (opens in a new tab) views. For other composite views, anchor is always "start". |
| angle | Number | ExprRef | Angle in degrees of title and subtitle text. |
| baseline | String | Vertical text baseline for title and subtitle text. 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 lineHeight rather than fontSize alone. |
| color | Null | Color | ExprRef | Text color for title text. |
| dx | Number | ExprRef | Delta offset for title and subtitle text x-coordinate. |
| dy | Number | ExprRef | Delta offset for title and subtitle text y-coordinate. |
| font | String | ExprRef | Font name for title text. |
| fontSize | Number | ExprRef | Font size in pixels for title text. |
| fontStyle | String | ExprRef | Font style for title text. |
| fontWeight | String | Number | ExprRef | 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 | String | ExprRef | The reference frame for the anchor position, one of "bounds" (to anchor relative to the full bounding box) or "group" (to anchor relative to the group width or height). |
| limit | Number | ExprRef | The maximum allowed length in pixels of title and subtitle text. |
| lineHeight | Number | ExprRef | Line height in pixels for multi-line title text or title text with "line-top" or "line-bottom" baseline. |
| offset | Number | ExprRef | The orthogonal offset in pixels by which to displace the title group from its position along the edge of the chart. |
| orient | String | ExprRef | Default title orientation ("top", "bottom", "left", or "right") |
| style | String | String[] | A mark style property (opens in a new tab) to apply to the title text mark. Default value: "group-title". |
| subtitle | Text | The subtitle Text. |
| subtitleColor | Null | Color | ExprRef | Text color for subtitle text. |
| subtitleFont | String | ExprRef | Font name for subtitle text. |
| subtitleFontSize | Number | ExprRef | Font size in pixels for subtitle text. |
| subtitleFontStyle | String | ExprRef | Font style for subtitle text. |
| subtitleFontWeight | String | Number | ExprRef | 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). |
| subtitleLineHeight | Number | ExprRef | Line height in pixels for multi-line subtitle text. |
| subtitlePadding | Number | ExprRef | The padding in pixels between title and subtitle text. |
| zindex | Number | The integer z-index indicating the layering of the title group relative to other axis, mark and legend groups. Default value: 0. |
Example: Customizing the Title Anchor
In this example, the title "A Custom Anchored Title" will be anchored at the start of the chart and will be bold with a font size of 20.
{
"title": {
"text": "A Custom Anchored Title",
"anchor": "start",
"fontSize": 20,
"fontWeight": "bold"
},
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}Example: Customizing the Title Position
In this example, we used "orient": "left" to set the title to the left.
{
"title": {
"text": "A Orient Customized Title",
"orient": "left"
},
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}Example: Add a Subtitle
In this example, we used subtitle property to set the subtitle and use subtitleFontSize and subtitleFontWeight to make it bold with a size of 20.
{
"title": {
"text": "A Title",
"subtitle": "A Subtitle",
"subtitleFontSize": 20,
"subtitleFontWeight": "bold"
},
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}Global Title Configuration
If you're looking to apply a consistent title style across multiple charts, you can use the title configuration (config: { title: {...} }). This method is handy for setting themes.
{
"config": {
"title": {
"font": "Calibri",
"fontSize": 18,
"color": "blue"
}
},
"title": "Consistent Title Style",
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}In this example, all titles will use the Calibri font, size 18, and blue color unless overridden by specific chart titles.
FAQs
1. How do I customize the font weight on title?
You can use the fontWeight property like this:
{
"title": {
"text": "A Normal Customized Title",
"fontWeight": "normal"
},
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}{
"title": {
"text": "A Bold Customized Title",
"fontWeight": "bold"
},
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}2. How do I use some font style like normal or italic on title?
Just use the fontStyle property like this:
{
"title": {
"text": "A Normal Customized Title",
"fontStyle": "normal"
},
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}{
"title": {
"text": "A Italic Customized Title",
"fontStyle": "italic"
},
"data": {"url": "data/barley.json"},
"mark": "bar",
"encoding": {
"x": {"field": "yield", "type": "quantitative"},
"y": {"field": "variety", "type": "nominal"}
}
}3. How do I customize the style of title with CSS?
For now, there is no way to customize the style of title with CSS.
4. How do I use HTML for the title?
For now, there is no way to inline HTML within the title.