Date zoom - Lightdash

Date zoom lets viewers change the date granularity of time-based charts on a dashboard without editing them. This is useful for zooming in to see daily patterns or zooming out to identify long-term trends. Date zoom works through controls, which behave like dashboard filters: each control is a pill in the dashboard toolbar that sets a granularity, and editors choose which charts each control governs. A dashboard has one built-in Default zoom plus any number of named controls you add.

How date zoom works

When viewing a dashboard, open a date zoom control and pick a granularity (Day, Week, Month, Quarter, Year, or a custom granularity). Every chart governed by that control updates to show data at the chosen granularity. Pick None to restore the charts’ original granularity. Key behaviors:

A control only affects charts that have a date dimension in their results.
The Default zoom governs every date-zoomable chart that isn’t attached to a named control. It’s hidden from viewers when every chart belongs to a named control.
Each named control governs only the charts you attach to it, using a specific date field per chart.
A chart can belong to at most one control. Charts already attached elsewhere show an In [control name] badge and can’t be selected by another control.
Changes made by viewers are temporary. Refreshing the dashboard restores the configured defaults.

Configuring available granularities

The granularities offered by every control on the dashboard are set on the Default zoom pill. Named controls can only offer granularities you’ve enabled here.

Configuring available date zoom granularities

Setting available granularities

Open the dashboard in edit mode
Open the Default zoom dropdown
Use the checkboxes to enable or disable granularities
At least one granularity must remain enabled
Save the dashboard to persist your changes

Setting a default granularity

You can pin a granularity as the default that’s automatically applied when the dashboard loads:

In the Default zoom dropdown, click the pin icon next to a granularity
The pinned granularity becomes the default
Click the pin again to remove the default

When a default is set, the dashboard automatically applies that granularity on load (unless overridden by a URL parameter). New controls also start at this granularity. Default granularities don’t apply when the dashboard is loaded with a granularity already specified in the URL.

Creating date zoom controls

Named controls let you point different charts at different granularities, or scope a single zoom to a chosen set of charts (including charts on other tabs).

Open the dashboard in edit mode
Click Add date zoom
In the Settings tab, give the control a name and pick its default granularity
In the Chart tiles tab, select the charts this control should govern. For each selected chart, choose the date field the zoom applies to. Charts are grouped by tab, and you can use Select all or a tab’s checkbox to attach many at once.
A control must target at least one chart before you can save. Click Save changes, then save the dashboard.

To edit an existing control, open its pill and choose Configure; to delete it, choose Remove. Viewers can change a control’s granularity from its pill, or pick Reset to default to return it to its configured granularity. Only charts with a date or timestamp dimension in their results are eligible to be attached to a control. A chart with no zoomable date field won’t appear in the Chart tiles list.

Using custom granularities

Custom granularities defined in your lightdash.config.yml appear in date zoom dropdowns alongside standard options, below a visual divider. This is useful for business-specific time periods like fiscal quarters or custom week definitions. See the dimensions reference for how to create and configure custom granularities.

Hiding or showing date zoom on a dashboard

You can control date zoom visibility at two levels:

Hide the whole date zoom section: in edit mode, click the eye icon on the date zoom section chip in the dashboard toolbar. When hidden, no date zoom controls are shown to viewers.
Hide an individual control: in edit mode, click the eye icon next to a control’s pill. A hidden control isn’t shown to viewers, but its granularity still applies to the charts it governs.

Hiding the whole section also stops the Default zoom’s pinned granularity from applying on load, so charts that aren’t attached to a named control render at the granularity they were saved with. Named controls keep applying their granularity to their charts, and a dateZoom parameter in the dashboard URL still overrides the saved granularity of unattached charts. Share the dashboard link without that parameter if every chart should keep its own granularity. In dashboards as code, hiding the whole section is isDateZoomDisabled: true in the dashboard’s config. Save the dashboard to persist visibility changes. You can show a section or control again at any time by toggling the eye icon back on in edit mode.

Referencing the date zoom in custom SQL

The currently selected date zoom granularity is exposed as a built-in reserved parameter called date_zoom. You can reference it in custom SQL anywhere parameters are supported:

${ld.parameters.date_zoom}

It resolves to the granularity name in lowercase (for example day, week, month, quarter, year, or a custom granularity name). When no date zoom is selected, the value is an empty string.

Custom SQL editor autocomplete listing ${ld.parameters.date_zoom} as a System variable

This is useful for adapting your SQL to the granularity the viewer picked on the dashboard, without defining a user parameter:

CASE
  WHEN ${ld.parameters.date_zoom} = 'week'  THEN 'Weekly'
  WHEN ${ld.parameters.date_zoom} = 'month' THEN 'Monthly'
  WHEN ${ld.parameters.date_zoom} = ''      THEN 'No date zoom applied'
  ELSE 'Other'
END

See Reserved parameters for the full list and behavior.

Referencing the granularity in chart labels

You can also reference the active granularity directly in chart labels — useful for axis names, series names and slice labels that should update when a viewer changes the date zoom (or when a chart is saved at a fixed granularity). Use the following placeholder in any supported label, where table_field is the base date dimension on the chart (for example orders_order_date):

${table_field.granularity}

At render time the placeholder is replaced with the granularity actually used to compile the query, lowercased — for example day, week, month, quarter, year, or a custom granularity label. For example, a y-axis label of Orders per ${orders_order_date.granularity} renders as Orders per week when the dashboard is zoomed to a weekly granularity. When you type $ in an axis name, big-value label, or gauge label, autocomplete lists every base date dimension on the chart so you can insert the placeholder without remembering the exact field id. You don’t need to remember the exact field id — Lightdash will insert the placeholder for you:

Cartesian axis names, big-value labels, and gauge labels — type $ in the label field and autocomplete lists every base date dimension on the chart.
Pie group labels and funnel step labels — click the insert date granularity icon inside the editable label field to insert the placeholder for the matching date dimension.

Supported labels:

Big value — label and comparison label
Bar, line, area, scatter, and mixed charts — x-axis name, y-axis name, and series names
Pie chart — group labels
Gauge — custom value label and custom percentage label
Funnel chart — step labels

If the referenced dimension isn’t on the chart, the placeholder is left untouched so you can see what’s missing.

Pie group labels and funnel step labels are per-category overrides — each custom label is keyed to a specific slice or step value. Because date zoom re-buckets dates (for example, the monthly 2024-07 slice becomes a weekly 2024-07-15 slice), an override set at one granularity stops matching after a viewer zooms to another and the custom label silently falls back to the raw value. If you need a label that survives date zoom, prefer the cartesian, big-value, or gauge labels above.

Date zoom in embedded dashboards

Date zoom can be enabled or disabled in embedded dashboards using the canDateZoom option in your JWT token:

{
  content: {
    type: 'dashboard',
    dashboardUuid: 'your-dashboard-uuid',
    canDateZoom: true,  // Enable date zoom in embed
  }
}

When canDateZoom is enabled, embedded dashboards render the dashboard’s configured date zoom controls (the Default zoom plus any named controls), not just a single global control. This applies to both JWT embeds and the React SDK, which share the same embedded dashboard rendering. See the embedding reference for complete details.

​How date zoom works

​Configuring available granularities

​Setting available granularities

​Setting a default granularity

​Creating date zoom controls

​Using custom granularities

​Hiding or showing date zoom on a dashboard

​Referencing the date zoom in custom SQL

​Referencing the granularity in chart labels

​Date zoom in embedded dashboards

How date zoom works

Configuring available granularities

Setting available granularities

Setting a default granularity

Creating date zoom controls

Using custom granularities

Hiding or showing date zoom on a dashboard

Referencing the date zoom in custom SQL

Referencing the granularity in chart labels

Date zoom in embedded dashboards