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.

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

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.

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.

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 dashboards - 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. Four channel placeholders are substituted with the clicked row's value for that channel: {{ x }}, {{ y }}, {{ color }}, {{ theta }}. Other Jinja-style {{ ... }} expressions pass through unchanged; use them for static strings only, not field names or variable references.

charts:
  sales_by_region:
    query: queries.sales
    type: bar
    x: region
    y: revenue
    link: "/regions/{{ x }}"   # {{ x }} becomes the clicked region

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 dashboard 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

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:. The value is a static URL; clicking the KPI value navigates to it.

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.