Skip to main content
The chart library is the in-product catalog of chart types built by Lightdash. Installing a chart type adds it to a single project, where anyone building charts can pick it from the chart type gallery like any built-in chart type.
The chart library is currently opt-in. Reach out to us to enable it for your organization.

​
Overview

A chart type is an installable visualization that extends Lightdash’s built-in chart types. The chart library offers a catalog of ready-made chart types built by Lightdash, with new additions over time. Examples include Big Number with Sparkline Trend, Customizable Cartesian Chart, and Heatmap. Rather than listing every option each one exposes, browse the library in-product for the current catalog and each chart type’s fields. Installed official chart types show a Built by Lightdash badge so people building charts can tell them apart from custom chart types built in your project.

​
Finding the library

Open Browse → Chart types (the puzzle icon) in the top nav, or go to a project’s Gallery page. There are two tabs:
  • Installed charts - chart types already installed in this project, including any custom ones your team built.
  • Chart library - chart types available to install from Lightdash’s catalog. Chart types already installed in this project don’t appear here.
Self-hosted admins: if the library source is unreachable (for example, from a restricted network), the Chart library tab is hidden and already-installed chart types keep working normally.

​
Browsing and installing

Click a card in the Chart library tab to open its detail modal. The modal shows:
  • Preview images of the chart type.
  • A description of what it’s for.
  • The fields the chart type expects, with each slot labeled as a dimension or metric.
  • The current version and its changelog.
Click Install to add the chart type to the project. It immediately appears in the Installed charts tab and in the chart type picker in the explorer for everyone in the project. Installs are scoped to a single project. Installing a chart type in one project doesn’t affect any other project.

​
Using an installed chart type in a chart

In the explorer, run a query, then open the chart type picker. Installed chart types appear alongside the built-in types, marked with a small installed from the chart type library badge and their own icons. When you select an installed chart type, Lightdash automatically maps your query’s fields to the chart type’s slots:
  • The General tab of the chart config shows each slot and lets you remap it. The field dropdowns can also add fields to your query that aren’t in it yet.
  • The remaining config tabs hold the chart type’s own options. These vary per chart type.
Save the chart like any other. It works in spaces and dashboards.
A saved chart keeps rendering the chart type version it was saved with, so published charts don’t change appearance when the library updates.

​
Upgrading a chart type

When a newer version is published, the installed chart type shows an update state, and its detail modal offers Upgrade to vX. The upgrade dialog shows:
  • The new version’s changelog.
  • How many saved charts in the project use the chart type, including how many are pinned to older versions.
Upgrading updates the version that new charts get. Existing saved charts continue to render the version they were saved with unless you choose to move them.

​
Forking to customize

Installed official chart types are read-only - you can’t edit their code directly. To customize one, click Fork to customize on the card or in the detail modal. Lightdash prompts for a name and creates an independent, editable copy as a custom chart type. A fork:
  • Does not receive library updates. It’s independent from the original.
  • Survives even if the original chart type is uninstalled.
Forking is only available where custom chart types are enabled. See Custom chart types for the requirements and how to work with them.

​
Uninstalling and recovery

Uninstall lives in the card’s actions menu and in the detail modal. Before you confirm, the dialog shows how many saved charts in the project are built on the chart type. Uninstalling does not delete those saved charts. They stay where they are, but render a placeholder saying their chart type was removed, with hints to pick another chart type or restore. Recovery paths:
  • Reinstall the same chart type from the library. Affected saved charts heal in place and render normally again.
  • Restore from Recently deleted (where soft-delete is enabled).
  • Edit an affected chart and pick a different chart type from the chart type picker.

​
Permissions