> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install chart types from the chart library

> Browse ready-made chart types built by Lightdash and install them into a project so anyone can use them like a built-in chart type

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.

<Info>
  The chart library is currently opt-in. [Reach out to us](/support) to enable it for your organization.
</Info>

## 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.

<Note>
  **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.
</Note>

## 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.

<Note>
  A saved chart keeps rendering the chart type version it was saved with, so published charts don't change appearance when the library updates.
</Note>

## 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](/explore/chart-types/custom-project-charts).

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](/explore/chart-types/custom-project-charts) 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

| Action                                  | Who can do it                                                                                                                 |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Use installed chart types in a chart    | Anyone who can build charts in the project                                                                                    |
| Install, upgrade, uninstall chart types | Project admins and developers                                                                                                 |
| Fork a chart type                       | Project admins and developers, in projects where [custom chart types](/explore/chart-types/custom-project-charts) are enabled |