Chart Interactions¶
Charts support hover interactions with tooltips and click-through via the
link: field, which turns chart elements into clickable drill-down links.
A link can open another board filtered to the clicked value, or set a
variable to filter the board it is on.
This page is the reference for each option. Links and Drill-Downs shows how links and variables combine into drill-downs, cross-chart filtering, and navigation.
Hover Tooltips¶
Charts automatically display tooltips when hovering over data points. Tooltips show the values for the hovered element.
charts: sales_chart: title: "Hover for Details" query: queries.sales type: bar x: month y: total_revenue
Many series at one x¶
On a stacked or grouped bar, or a multi-series line or area, the tooltip lists every series at the hovered x: the first 7 as rows, the rest as "+N", then the total. Above 100 series it shows only the hovered series and the total. Both cutoffs are set board-wide under style.charts.tooltip:
style: charts: tooltip: max_rows: 10 group_limit: 30
max_rows: series rows shown before "+N". One series past the cap shows as its own row instead of "+1". The hovered series always shows.group_limit: the series count above which the tooltip shows only the hovered series and the total.
Add columns to the tooltip¶
A tooltip shows the chart's own fields. To show other columns of the query, list them under tooltip:. Each entry is a column name, or an object with a label and a format:
source: examples_db
charts:
revenue_by_category:
type: bar
title: Revenue by Category
query:
sql: |
SELECT
category,
SUM(revenue) AS revenue,
COUNT(*) AS order_count,
ROUND(SUM(revenue) / (SELECT SUM(revenue) FROM ecommerce_orders), 3) AS share
FROM ecommerce_orders
GROUP BY category
ORDER BY revenue DESC
x: category
y: revenue
tooltip:
- order_count
- column: share
label: "% of revenue"
format: ".1%"
rows:
- revenue_by_category
- Label: the entry's
label, else the chart'sfield_labels:entry for the column, else the label derived from the column name. A label cannot contain:or;. - Format: the entry's
format, else the query'sformats:entry for the column. Numbers and dates take a number or date format; any other column prints as written. A format on a text column is an error. A null value prints as an em dash. - Where the rows go: after the mark's own rows (and before a stacked chart's total), set off by one divider the chart draws for you. On a stacked or grouped bar, or a multi-series line or area, the card lists every series at the hovered x; the rows you add sit under the series you are pointing at, indented and muted, and show only for that series.
- Layers: the rows go on the base marks only; a layer's marks keep their own card.
- Errors: a column the query does not return fails the chart, naming the column.
tooltip: works on bar, line, area, scatter, pie and donut. It is an error on any other type, and on a chart with y_start:, a histogram, or a scatter with a list y:.
Hover emphasis¶
Hovering a chart makes the part the tooltip describes easier to find.
- Bars, histograms, pie and donut slices, and heatmap cells: the marks the tooltip is not describing recede. They keep their shape and position but blend toward the chart background, so the bar (or grouped cluster, stacked column, slice, or cell) under the cursor stands out.
- Lines, areas, and scatter points: a dot marks each datum the tooltip describes, and a neutral line drawn from the theme's grays drops from it to the plot's baseline. On a stepped line, the dot sits in the middle of the step.
Value labels printed on a bar recede along with their bar. Every other label stays lit: direct labels, a donut's center total, and series labels never recede. In small multiples, only the panel under the cursor recedes.
Apart from a selected value, nothing about the rendered chart changes until you hover. Turn it off
board-wide with style.charts.hover_emphasis.visible:
style: charts: hover_emphasis: visible: false
A chart whose color encodes a value (a continuous color scale) never recedes, whether or not its legend is shown, because a receded color would read as a different value on that scale. Charts colored by category recede normally.
Legend hover and clicks¶
On a chart colored by category, hovering a legend entry, or a series name drawn beside its line or bars, keeps that series lit and recedes every other series and its legend entry, the same way hovering a mark does. It previews what a click on that entry shows. Scatter legends do not preview.
Clicking a legend entry, or a series name drawn beside a line or bars, on a bar, line, area, or scatter chart redraws that chart with only some of its series:
- Click an entry to show only its series.
- Click another entry to add its series to the ones shown, or a shown entry to take its series out. Taking out the last one, or adding the last hidden one, shows every series again.
Tab to an entry or a series name and press Enter or Space to do the same. The
value axis zooms to the series shown, with the headroom and tick labels a chart
holding only those series would get, and the plot stays the same size, so the
chart does not jump between views. The axis rescales only along the values: a
chart's categories, and a scatter's category axes and shapes, stay as they were.
An axis pinned to zero stays pinned to zero, and a view that shows nothing keeps
the whole chart's axis, as does a stacked bar whose shown piles all run below
zero. Every series keeps its color, and every legend entry and series name stays
drawn, with the hidden ones receded, so you can click another one. (On a stacked
area or bar, a hidden series has no name beside the plot; the space for it
stays.) A click reloads the board, and only cached query results avoid running
a query again. The view is not visible to SQL, and no other chart changes: the
choice lives in the page URL as _dct_legend_<chart-id>, so a link to the page
keeps it, and the board's Reset item clears it. Pie, donut, and 100%-stacked
charts only preview on hover, and so do charts that plot several measures
(y: [revenue, profit]), charts with layers or a support table, charts colored
by a number, and charts split into small multiples.
On a chart with a color-keyed variable link, a legend click sets that variable instead, which filters every chart that reads it. A multiselect adds and takes out options the same way; a select or radio switches to the clicked option, and clicking the one it holds shows every option again. Series names beside the chart act the same, for the options that have rows.
Cross-File Query References¶
You can reference queries from external files using the file.yml#query_name syntax:
charts: sales_chart: query: shared_queries.yml#monthly_revenue # External file reference type: bar x: month y: revenue
This is useful for: - Sharing queries across multiple boards - Keeping doc examples short by referencing common queries - Organizing large projects with separate query definition files
Paths are resolved relative to the current file's directory.
Drill-Down Links (link:)¶
Set link: on a chart to turn each data point into a clickable link. The
value is a URL template filled from the clicked row:
{{ x }},{{ y }},{{ color }},{{ theta }}read the column that channel plots.- Any other
{{ name }}reads the row's column of that name, plotted or not.
charts: sales_by_region: query: queries.sales type: bar x: region_name y: revenue link: "/regions/detail?id={{ region_id }}" # region_id is in the query, not on the chart
A channel name always reads its channel, never a column of that name, and fails the chart when the chart does not plot that channel. Any other name that is not a column of the query fails the chart too. A mark that stands for several rows (a histogram bin, a counted map point, a geoshape map) has no row to read a column from, so a column placeholder fails there too.
Board-root paths (/path/…) are automatically rewritten for dct serve and
Cloud; the same YAML works in both environments.
In-page variable updates¶
A link: starting with ? updates a board variable without navigating
away. Use this for cross-chart filtering within the same board:
charts: by_category: query: revenue_by_category type: bar x: category y: revenue link: "?selected_category={{ x }}" # updates the selected_category variable
Once the variable holds a value, the marks that carry it keep their ink and the
rest recede toward the chart background, the way a bar's neighbors do under a hover, with their
outlines, value labels, slice labels, and the series' legend entries and endpoint labels. The emphasis is part of the rendered SVG, so it
survives PNG and PDF export, and it clears with the variable. It needs a link
of exactly ?name={{ color }} on a bar, area, pie, or donut
chart with a color field, or ?name={{ x }} on a bar with no color field and no date axis. A
link keyed by anything else (a multi-series bar's category, a
date axis, a heatmap or histogram cell) leaves every mark as drawn, as does a chart colored
by a continuous scale. A donut's center total and overlay layers never recede. Line and scatter charts draw as authored after a click.
With a ?name={{ color }} link, the chart's legend entries set the variable
too, on bar, line, area, pie, and donut charts: clicking "strict" in the
legend sets the variable to strict, as clicking a strict bar does. Clicking
the entry of the value the variable already holds clears it. A query that
filters on the variable then returns only that series, so the chart, and every
other chart that reads the variable, shows only that series.
When the variable is a select, radio, or multiselect with options, the
legend keeps every option after the filter, with the ones not selected receded,
so you can click another. Each series takes its color from its place in the
option list, so it keeps that color whatever is selected. On a multiselect,
a click adds a series to the selection or takes it out, and taking out the
last one shows every option again:
variables: metric: options: static: [strict, directional] queries: pass_rates: sql: | SELECT arm, metric, rate FROM eval_results WHERE {{ filter('metric', metric) }} charts: pass_rate_by_arm: query: pass_rates type: bar x: arm y: rate color: metric link: "?metric={{ color }}"
Direct labels follow the legend: a stacked bar or stacked area keeps a receded, clickable label for every option too. In a live board, hovering a legend entry or a direct label also brings that series' line in front of the lines that overlap it.
While the variable holds a value (or, with no link:, while clicking the legend has hidden series), a small "× CLEAR" control appears in the label
column, left-aligned with the direct labels and just below the lowest one (above
the highest when there is no room below); a boxed legend carries it below its last entry. Click it, or focus it and press Enter,
to set the variable back to all. Where the label column is too narrow for the words, it
shows a lone "×" with a hover title. The control exists only in live boards: a static
SVG, PNG, or PDF export never shows it.
link: works on chart types that render individual data elements per row
under the Vega-Lite pipeline: bar, line, area, point, and other
VL-backed marks.
KPI charts¶
KPI charts also support link:. Clicking the KPI value navigates to it.
{{ name }} reads the column of that name from the KPI's one row.
Tables¶
Tables support link: at both the chart root and per column, and the two are
distinct affordances:
- A chart-root
link:makes the whole row clickable. It renders as one row-wide selection band that highlights on hover; clicking anywhere on the row (except a cell that has its own link) navigates to the row destination. - A column
link:instyle.columnsmakes that column's cells clickable links, rendered inline and inked. A cell link always wins the click over the row band beneath it.
charts: tickets_table: type: table query: open_tickets link: "/zendesk/tickets/detail?id={{ ticket_id }}" # whole-row link style: columns: status: link: "/zendesk/backlog/?status={{ status }}" # this column's cells link here ticket_id: label: Ticket # no column link; clicking it follows the whole-row link
A column link is a per-cell link on that column only. It does not fall
through to other columns; plain columns with no column link are not inked as
links; they are just part of the clickable row when a chart-root link: is
set. Summary and total rows never get the row band.
Opening a link in a modal, preview, or new tab¶
A link: (chart root, table column, or header_link:) also takes an object
form whose open: says how a click opens the target:
link: url: "/regions/detail?region={{ x }}" open: modal # page | modal | preview | new_tab
A string link: and an object without open: take the root board's
links.open, which is page unless set. Only the root board sets it; a nested
board that authors links: is an error:
links: open: preview # string links and links without open: open as a preview
Precedence: the link's own open:, then the root board's links.open, then
page. A ?variable= link, a table cell's filter link, an email or url
column's implied link, a KPI's implied link and a custom chart's per-row link
stay a page. See Board link settings.
open: |
Click result |
|---|---|
page |
Navigates to the target, like a string link:. |
modal |
Opens the target board in a dialog over the current one, sized to fit it. |
preview |
Shows the target board scaled down in a small window beside the clicked mark. A click outside, Escape, or a page scroll closes it. |
new_tab |
Opens the target in a new browser tab, in an exported file too. |
- A
modalorpreviewtarget must be a board. A link to another site opens in a new tab: most sites refuse to be shown inside another page. - The board inside has no navigation chrome. Its filters work, and its links open inside the same window; the back arrow returns to the previous board.
- The window's bar has an open-in-new-tab button. Drag the bar to move the window, or its edges and corners to resize it; the board scales with it.
- Cmd/Ctrl-click and middle-click still open the target in a new tab.
- Modals and previews work in
dct serve, Cloud, and the playground. An exported HTML or SVG file follows the link as a normal page navigation.
Related¶
- Links and Drill-Downs - How links and variables build every interaction
- Linking Between Boards - Board path syntax and resolution
- Charts Overview - Chart field reference
- Variables - Using variables with charts
- Expressions - Using expressions in query filters