> ## 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.
# Configure your charts
> Learn about the configuration options available for most chart types in Lightdash.
Most chart types have very similar configuration options, so we put them all together below.
## Layout
This is where you can pick the columns from your results table that you want to plot on your x and y axes or that you want to group by.
You can group by up to 3 fields in your chart.
For bar charts, this is also where you have the option to stack your bars, or leave them unstacked (grouped).
## Series
The series tab is where you can adjust how your chart shows each data series. A **data series** is a set of related data points plotted on a chart. For example, the number of new users created each day over a set of dates is a series. In a bar chart, a series is represented by bars of the same color; in a line chart, a series is represented by a single line. You can see a list of the series for your chart in the **Series** menu, and on the chart legend.
The options available in here will depend on the data in your chart. But, in here you can:
* Set the chart type for each series
* Change series labels or colors
* Put series on a left or right y-axis
* Show value labels or group totals on data points
* Hide a series from your chart
### Custom colors (conditional formatting)
On bar charts, toggle **Apply custom colors** in the Series tab to recolor bars based on rules you define. Each rule targets a specific metric via the **Target metric** picker and only recolors that metric's bars — other metrics keep their default colors, even where their values match the same condition.
For example, on a chart with `revenue` and `orders` bars grouped by product category, you can add one rule that turns `revenue` bars red when revenue is below `1000`, and a second rule that turns `orders` bars orange when orders are below `50`. Categories where only revenue is below the threshold keep the default color on their `orders` bar, and vice versa.
**When to use it**
* **Conditional formatting** — highlight bars whose value matches a rule (e.g. below target, above threshold). Available on bar charts with one or more metrics, including stacked and 100% stacked bar charts when the stack is built from multiple metrics. Every series on the chart must be a bar; mixed bar/line charts are not supported.
* **Color by category** — assign a fixed color to each x-axis category. Only available on single-metric, non-stacked bar charts. When both modes are available, use the Category / Conditional formatting toggle at the top of the section to switch between them.
**Stacked and 100% stacked bar charts**
On stacked and 100% stacked bar charts, all rules share a single **Target metric** — changing the target on any rule retargets every rule together, and new rules follow the existing target. Matching segments get a fill override on the chart, while the legend swatch keeps the base series color so the series remains identifiable.
On 100% stacked bar charts, rules evaluate the raw metric value, not the normalized percentage. Two segments with near-identical rendered heights can therefore color differently if their raw values straddle the threshold — for example, a rule `revenue is less than 1000` colors a `$900` segment even when it renders at the same height as an `$1,100` segment in a different category.
Not yet supported: pivoted (grouped) stacks, and color by category on any stacked layout.
**Configuring a rule**
1. In the Series tab, toggle **Apply custom colors** on. A new rule opens expanded so its inputs are immediately visible.
2. Pick the **Target metric** the rule applies to. On stacked and 100% stacked charts this target is shared across all rules.
3. Add one or more conditions (for example, `revenue is less than 1000`) and choose a color. A rule with no condition filled in shows **No condition set** until you add one.
4. Add more rules for other metrics or other thresholds as needed.
## Axes
In this section you have options to:
* Override the default text for your axes labels
* Adjust sort order of your x-axis
* Rotate x-axis labels
* Set the min and max axis values for your y-axes (or keep the default auto y-axis range)
* Show x-axis and y-axis grid lines
* Hide x-axis completely
* Hide y-axis completely
* Enable a scrollable chart for charts with many x-axis values
### Referencing the active granularity in axis and series labels
Axis names and series names support a `${table_field.granularity}` placeholder that resolves to the active date granularity (for example `day`, `week`, `month`) — including the granularity selected via [date zoom](/guides/date-zoom). This lets a label like `Orders per ${orders_order_date.granularity}` render as `Orders per week` when viewers zoom to a weekly granularity.
See [Referencing the granularity in chart labels](/guides/date-zoom#referencing-the-granularity-in-chart-labels) for the full syntax and the complete list of supported labels.
### Scrollable chart
For bar, line, and area charts with many x-axis values, turn on **Enable scrollable chart** to display a fixed-size window of data points that viewers can scroll through, instead of squeezing every value into the chart.
When enabled, you can configure:
* **Initial scroll position** — Choose whether the chart opens anchored to the **Start** (oldest or first values) or **End** (newest or last values) of the data. Use **End** for time series where the most recent values matter most.
* **Visible items** — Set how many x-axis items appear in the window at once (between 2 and 100, default 10).
Both settings are saved with the chart and are also respected when the chart is defined as code.
## Display
This tab is where you're able to control the legend, reference lines, and [custom tooltips](/guides/custom-tooltip) in your chart.
### Reference lines
You can add reference lines to your charts to easily visualize goals or thresholds.
To add a reference line, click `+ Add` under Display -> Reference lines.
You have these options in the settings:
* Select a field you want to linke to your reference line (Page views in the image above)
* Set a static value (50,000 in the image above)
* Add a label (`Halfway to our goal!` in the image above)
* Change the line color (green in the image above)
Most reference lines are static values, but you can also use these key words to plot a dynamic value: `min`, `max`, `median`, `average`.
That way your reference line will automatically update to the global min, max, median, or average of the field you selected. See image below for examples.
If you select a field plotted on your x-axis, then your line will be vertical. If you select a field plotted on your y-axis, then your line will be horizontal.
If your reference line label is cropped off your chart, try adjusting your [right margin](#margins).
### Legend
You can add and adjust the legend in your chart to help people understand what data's been plotted.
* Show or hide the legend
* Choose a **Placement** for the legend:
* **Chart area** overlays the legend on top of the plot. You can fine-tune its `position`, scroll behavior, and orientation (see below).
* **Outside right** or **Outside left** renders the legend beside the plot and reserves space in the chart grid so the legend never overlaps your data. When you pick an outside placement, set the **Legend area width** (in `%` or `px`) to control how much horizontal space is reserved for the legend.
* When **Placement** is set to **Chart area**:
* Adjust the position of the legend on your chart. The values in `position` are the coordinates of the legend on your chart. They can either be numbers or percent. We suggest using %.
* If you want the position to be in the bottom right, you would set: Right = 0%, Bottom = 0%. For the legend to be in the middle of the chart, you'd set: Top = 50%, Left = 50%.
* Set your legend to scroll (if you have so many groups that they overlap your chart).
* Orient the values in your legend to form a list vertically, or horizontally.
#### Saving the default legend selection
On cartesian charts (bar, line, area, scatter, mixed), the legend entries you toggle off in the chart editor are saved with the chart. When someone opens the chart again — in the explore view, a saved chart, or a dashboard — the same series start greyed out. Disabled series stay listed in the legend so viewers can still click them back on for their session; those ephemeral toggles are not written back to the saved chart.
To change the default:
1. Open the chart in the editor.
2. Click legend entries to disable or re-enable series. For example, on a chart pivoted by `product_category`, click **Apparel** and **Home Goods** in the legend to focus on **Electronics**.
3. Click **Save**. The next time anyone opens the chart, only **Electronics** is plotted, with **Apparel** and **Home Goods** greyed out in the legend.
Pie and funnel charts do not persist legend selection — toggling their legend entries stays ephemeral.
**In chart-as-code YAML**, the saved selection lives on `echartsConfig.legend.selected`. It's an optional map from legend entry name to boolean, and only entries set to `false` are stored — series that don't appear in the map default to visible, so new series (for example a new quarter added to a pivoted chart) show up automatically. Re-enabling every series in the editor and saving removes the `selected` field entirely.
```yaml theme={null}
echartsConfig:
legend:
show: true
selected:
Apparel: false
Home Goods: false
```
## Data
The Data tab lets you trim what gets shown on the chart without changing the underlying query. Both controls run client-side on the already-fetched results, so totals, exports and underlying data are unaffected.
### Limit displayed rows
Toggle **Limit displayed rows** to show or hide a slice of rows from the top or bottom of your results.
The control reads as a sentence:
* **Show / Hide** — keep only the targeted rows, or remove them.
* **First / Last** — anchor to the top or bottom of the results.
* **N** — how many rows to target (default 50).
Examples:
| Setting | Effect |
| ---------------------- | ------------------------------------------------------------------- |
| Show the first 50 rows | Plot only the top 50 rows; ignore the rest |
| Hide the last 1 row | Drop the bottom row (useful when the trailing period is incomplete) |
| Show the last 12 rows | Plot only the most recent 12 rows of a time series |
The row limit only affects what's drawn on the chart. Your query still returns the full result set, totals are calculated against all rows, and CSV exports include every row.
### Column limit
When your chart has a pivot dimension, the **Column limit** controls how many pivot groups (and therefore series) are drawn. Lightdash keeps the first N pivot groups in display order and drops the rest.
This is useful when a pivot dimension has many values and the chart becomes hard to read. Leave the field blank for no per-chart limit (the system-wide pivot limit still applies — see [the pivot table column limits reference](/references/chart-types/table#column-limits)).
The column limit field only appears when a dimension is configured in the **Group** field.
## Margins
The Margin tab is where you're able to add or remove margin around the grid. Removing margin means that your chart will fill more of the space in the chart tab. Adding margin will shrink your chart into a smaller space.
You can either add numbers (e.g. 50) or percent values (e.g. 50%) to the margin settings listed. The default margin is set to `top` = 70, `bottom` = 30, `left` = 5%, `right` = 5%
