Creating Lens Chart Documentation Pages

Use these instructions when creating or updating a documentation page for a Kibana Lens chart type in explore-analyze/visualize/charts/.

Before writing: verify settings against source code

Use the lens-chart-settings skill to verify all UI labels, option values, and rendering order against the Kibana source code before documenting them. Never guess UI labels.

Research resources

Kibana source code paths

Many visualizations use shared components (in shared_components/) that accept different props per chart. Always check the visualization-specific wrapper to see which props are passed, rather than assuming all shared component options are available.

EUI data visualization guidelines

• Part-to-whole comparisons (pie, donut, treemap)
• Dashboard good practices
• Categorical color palettes

Existing content to check

• Main Lens page: explore-analyze/visualize/lens.md — check for content to reference or deduplicate.
• Other chart pages: explore-analyze/visualize/charts/*.md — follow established patterns.
• Shared snippets: explore-analyze/_snippets/lens-*.md — reuse instead of duplicating.

Key snippets:

When creating a new chart page, update lens.md to link to it and remove any duplicated content.

File location and frontmatter

Place the file at explore-analyze/visualize/charts/<chart-type>.md with this frontmatter:

---
navigation_title: <Chart type> charts
description: Instructions and best practices for building <chart type> charts with Kibana Lens in Elastic.
---

Chart-specific dimensions

Page structure

Follow this exact section order. Every chart page uses it consistently.

1. Title and introduction

# Build <chart type> charts with {{kib}}

• One paragraph (2-3 sentences): what the chart does and when it's useful. Focus on purpose.
• Weave in specific actionable constraints (e.g., "works best with a maximum of 6 slices"). Skip generic advice.
• Do not create a separate "When to use" section.
• A line: You can create <chart type> charts in {{kib}} using [**Lens**](../lens.md).
• A hero image of a representative example.

2. "Build a <chart type> chart" section

Include the prerequisites snippet before the stepper:

:::{include} ../../_snippets/lens-prerequisites.md
:::

Then use the stepper directive:

::::::{stepper}

:::::{step} Access Lens
**Lens** is {{kib}}'s main visualization editor. You can access it:
- From a dashboard: On the **Dashboards** page, open or create the dashboard where you want to add a <chart type> chart, then add a new visualization.
- From the **Visualize library** page by creating a new visualization.
:::::

:::::{step} Set the visualization to <Chart type>
New visualizations often start as **Bar** charts.

Using the **Visualization type** dropdown, select **<Chart type>**.
:::::

:::::{step} Define the data to show
[Chart-specific data configuration steps]
:::::

:::::{step} Customize the chart to follow best practices
[Best practices as a definition list]
:::::

:::::{step} Save the chart
- If you accessed Lens from a dashboard, select **Save and return** to save the visualization and add it to that dashboard, or select **Save to library** to add the visualization to the Visualize library and reuse it later.
- If you accessed Lens from the Visualize library, select **Save**. A menu opens and offers you to add the visualization to a dashboard and to the Visualize library.
:::::

::::::

Key conventions:

• Access Lens and Save the chart steps are identical across all chart pages. Copy them verbatim.
• Define the data to show lists numbered steps for chart-specific dimensions, then "Optionally:" for additional dimensions. Link dimension names to their settings sections (e.g., [**Slice by**](#slice-by-settings)).
• Customize the chart uses definition list format. List 4-6 actionable best practices. End with a line pointing to the full settings reference.

3. Advanced scenarios (optional)

Only include when teaching a non-obvious technique users wouldn't discover on their own:

• Using formulas (e.g., computing error rates as a percentage)
• Configuring multiple metrics for completion progress (waffle)
• Setting up dynamic bounds or goals from data (gauge)
• Defining custom color ranges (heat map)
• Configuring color bands with thresholds (gauge)

Do NOT create scenarios that are just "use the chart with different fields". For simpler chart types, the Examples section is sufficient.

When including scenarios:

• Each scenario gets its own ## or ### heading with an anchor ID.
• Use concrete examples based on Kibana Sample Data when possible.

Sample data considerations

• The response field in web logs is a text field — KQL filters must use pattern matching (response: 2*), not numeric comparisons.
• In sample ecommerce data, taxful_total_price and taxless_total_price are identical.
• Multiple comparable numeric fields are rare. When sample data doesn't support a scenario, use a conceptual example with realistic field names and add a :::note explaining users need to adapt to their data.

4. "<Chart type> settings" section

Document every configuration option in the Lens editor, organized by dimension/panel.

Structure each dimension as:

### <Dimension> settings [<dimension>-settings]

Within each dimension, use two top-level definition list entries: **Data** and **Appearance**.

Data:

• List all available functions/aggregation types.
• For each function, document the Field selector first, then function-specific sub-options as nested bullets.
• Field selector conventions:
  • Top values: Supports up to 4 fields. Multiple fields create multi-term grouping. Fields can be reordered by dragging.
  • Date histogram: Single date field only.
  • Intervals: Single numeric field only.
  • Filters: No field selector (KQL queries reference fields directly).
• Reuse shared snippets wherever applicable.

Appearance:

• List visual options: Name, Value format, Color, Series color, Color mapping, etc.

After dimension-specific settings, add a ### General layout section for global settings ({icon}`brush` Style and legend). Split into #### Style settings and #### Legend settings as needed.

Legend settings vary by chart type:

5. "<Chart type> examples" section

• 2-4 real-world examples using Kibana Sample Data.
• Use definition list format with bold example title.
• Structure each example:
  • * Example based on: <sample data set name>
  • Configuration keys as bullet points (Slice by, Metric, Style, Legend, etc.)
  • An image of the result, sized with "=60%" or "=70%"
• Showcase different features (e.g., basic config, donut variant, filters, multiple metrics).

Chart-page-specific formatting

For general syntax, refer to the docs-syntax-help skill. These conventions are specific to chart pages:

Images

• Store at explore-analyze/images/<image-name>.png
• Reference with: ![Alt text](/explore-analyze/images/<image-name>.png "=60%")
• Sizing: "=50%" for smaller inline images, "=60%" for examples, "=70%" for settings screenshots.
• Alt text should be descriptive, not "screenshot".

Icons

For the legend icon, use: ![Legend icon](/explore-analyze/images/kibana-legend-icon.svg "")

Cross-references

• Other chart types: [bar charts](bar-charts.md)
• Lens page: [**Lens**](../lens.md)
• Lens features: [Assign colors to terms](../lens.md#assign-colors-to-terms)
• Sample data: [sample data](/manage-data/ingest/sample-data.md)

Internal links

Link from steps to settings sections:

2. Configure the [**Slice by**](#slice-by-settings) dimension.
3. Configure the [**Metric**](#metric-settings) dimension.

Link from best practices to advanced scenarios when relevant.

Variables

Use {{kib}} (Kibana), {{es}} (Elasticsearch), {{data-source}} (data view / data source).

Checklist

• Frontmatter has navigation_title and description
• Hero image exists and is referenced
• "Build a chart" stepper uses standard Access Lens / Save steps
• Prerequisites snippet included before the stepper
• All settings verified against Kibana source code (use lens-chart-settings skill)
• All settings from the Lens editor are documented in the Settings section
• Shared snippets included where applicable (not duplicated)
• Examples use Kibana Sample Data and include images
• Internal links from steps to settings sections
• Links from best practices to related advanced scenarios
• lens.md updated to link to the new page