Skip to main content
Project chart types are reusable chart types you build for your project. You describe the chart you want, Lightdash builds it, and anyone in the project can then use it like a built-in chart type. Open Configure in the Explorer, click Change, and pick it from the Project group of the chart type picker. For a one-off chart written directly as a Vega-Lite spec, see Custom Vega charts. A project chart type is a chart type you build once and reuse. Describe the chart you want - a calendar heatmap, a hexbin map, a custom KPI layout - and Lightdash builds it, along with the inputs it needs (for example a “Category” dimension and a “Value” metric). Anyone in the project can then pick it as a chart type, map their own fields to its inputs, and save the result like any other chart. The same chart type can power many saved charts, each with its own query and field mapping.
Project chart types are an enterprise feature and require the data apps runtime to be enabled.

​
Browsing chart types

Every chart type in the project lives in the gallery. Go to Browse and pick Chart types. Each card previews the chart type with sample data. Click a card to see its description, who built it, its inputs, and its current version, and to preview it in the Explorer, edit it, or delete it.

​
Building a chart type

Click New chart type in the gallery to open the builder, then describe the chart you want. The builder previews the chart type with sample data as it’s built. The Configure panel beside the preview holds the display options the chart type declares, along with a color palette to preview it against. Follow-up prompts create new versions, and History opens a panel where you can view an earlier version or restore it. Name and describe the chart type in the header - that’s what people see in the gallery and in the chart type picker. When it looks right, click Preview in explorer to try it against a real query.
You can also start one from any chart, without leaving the Explorer: open Configure, click Change, and choose Create new chart type in the Project group. The builder opens in the chart panel and previews against your query’s real results.
Chart types can also be developed on your machine and uploaded with the CLI. See Chart types as code.

​
Linking external connections

Chart types render in the same sandbox as data apps, so they can only reach the network through external connections. That covers two cases: calling a third-party API while the chart renders, and showing images from a URL field in your results. Without a linked connection, the sandbox blocks images from any other origin. A project admin registers the connection once, then whoever builds the chart type links it from the builder.
1

Register the connection

Go to Project Settings → Data app connections and click Add connection. Enter the Base URL of the host the chart type needs to reach and pick the auth method that host requires. A public image host needs None.
2

Allow images from it

If the chart type shows images, turn on Allow public images in linked apps. Linked chart types can then load images straight from that origin, in <img> tags or CSS. Leave it off for hosts you only call for data.
3

Choose who can link it

Set Who can link this connection? to Data app and chart type builders so editors can attach it from the builder. Admins only keeps it out of everyone else’s picker.
4

Attach it in the builder

Open the chart type in the builder, or start a new one, and click Add external connections in the prompt bar. Tick the connection, then describe the chart, or send a follow-up prompt such as “show the image from the Image URL input”. The link is created when that build runs, so an existing chart type needs at least one follow-up prompt to pick it up.
5

Check it in the Explorer

Click Preview in explorer, run a query that includes the image URL field, and map it to the chart type’s input. The images should render.
Once linked, the connection stays with the chart type across versions and everywhere it renders: the builder preview, the Explorer, saved charts, dashboard tiles, and embedded dashboards. The indicator in the prompt bar counts linked connections. Open it and untick a connection to unlink it. Unlinking only removes the link, so the generated code keeps calling the connection until you build a new version.

​
Using a chart type in a chart

1

Run your query

Select the dimensions and metrics your chart needs and run the query. You have to run it before you can pick a custom chart type.
2

Pick the chart type

Open Configure, click Change, then pick one from the Project group in the chart type picker. Only chart types that finished building are listed.
3

Map your fields

Each of the chart type’s inputs gets a field picker, the same as configuring axes on a bar or line chart. Required inputs can’t be cleared.
The chart re-renders as you change the mapping or the underlying query.

​
Saving and dashboards

Save the chart like any other chart. The saved chart remembers which chart type it uses and how its inputs are mapped. Saved charts render in chart view and as dashboard tiles, driven by each surface’s own query - dashboard filters and date zoom apply like any other chart tile.

​
Chart types as code

Chart types round-trip through the CLI as their own resource, separate from data apps. Each one downloads to lightdash/chart-types/<slug>/ as a locally buildable project you can version in git, edit, validate with lightdash apps validate, and upload back:
A chart type’s identity is the slug in its lightdash-app.yml manifest, upserted in the target project on upload. The manifest also carries a vizSchema field with the chart type’s declared inputs, so the inputs round-trip with the source. Saved charts reference their chart type by that slug in chart YAML (the dataAppVizSlug field), which keeps chart files portable across projects and instances:
  • Downloading charts brings the chart types they render with along automatically, into lightdash/chart-types/.
  • Uploading a chart resolves the slug in the target project. If the chart type doesn’t exist there, the chart upload fails with a message to run lightdash upload --chart-types <slug> first.
  • Chart YAML written before slug references carries a dataAppVizUuid instead. Uploads accept it, but new downloads always write the slug.
The folder layout and server-side build pipeline are the same as for data apps — see Data apps as code, and the --chart-types flags on lightdash download and lightdash upload for the full flag lists.

​
Permissions

Chart types are available across the whole project. They don’t live in spaces and can’t be moved into one.
  • Anyone who can view a chart can see the chart type it renders with.
  • Editors and above can build new chart types.
  • You can edit and delete the chart types you built. Project admins can edit and delete any of them.