Skip to content

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
Revenue by Category01m2m3m4mElectronicsAccessoriesTools Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶
  • Label: the entry's label, else the chart's field_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's formats: 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.


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: in style.columns makes 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.

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 modal or preview target 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.