Docs Lens Chart Page

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

| Chart type | Source path | |------------|-------------| | Partition (pie, donut, treemap, mosaic, waffle) | x-pack/platform/plugins/shared/lens/public/visualizations/partition/ | | XY (bar, line, area) | x-pack/platform/plugins/shared/lens/public/visualizations/xy/ | | Metric | x-pack/platform/plugins/shared/lens/public/visualizations/metric/ | | Datatable | x-pack/platform/plugins/shared/lens/public/visualizations/datatable/ |

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:

| Snippet | Purpose | |---------|---------| | lens-prerequisites.md | Prerequisites paragraph (data views, ES\|QL mode) | | lens-rank-by-options.md | Top values rank-by options | | lens-value-advanced-settings.md | Advanced settings for value/metric dimensions | | lens-breakdown-advanced-settings.md | Breakdown advanced settings | | lens-histogram-settings.md | Date histogram settings | | line-chart-legend-settings.md | Legend settings including Statistics (line/area) | | line-chart-style-settings.md | Style settings (line/area) |

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/.md with this frontmatter:

---
navigation_title:  charts
description: Instructions and best practices for building  charts with Kibana Lens in Elastic.
---

Chart-specific dimensions

| Chart type | Primary dimensions | Additional dimensions | |------------|-------------------|----------------------| | Pie / Donut | Slice by, Metric | (none) | | Bar / Line / Area | Horizontal axis, Vertical axis | Breakdown | | Metric | Primary metric | Secondary metric, Maximum value | | Gauge | Metric | Minimum value, Maximum value, Goal | | Table | Metrics, Rows | Split metrics by |

Page structure

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

1. Title and introduction

# Build  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 charts in {{kib}} using [**Lens**](../lens.md).
• A hero image of a representative example.

2. "Build a 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, then add a new visualization.
- From the **Visualize library** page by creating a new visualization.
:::::

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

Using the **Visualization type** dropdown, select ****.
:::::

:::::{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. " settings" section

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

Structure each dimension as:

###  settings [-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:

| Setting | XY charts | Partition charts | Notes | |---------|-----------|-----------------|-------| | Visibility | Yes | Yes | Auto / Show / Hide | | Position | Yes | No | Partition charts don't pass location | | Statistics | Yes | No | Controlled by defaultLegendStats | | Nested legend | No | Yes (>1 group) | Multiple Group by dimensions required | | Label truncation | Yes | Yes | | | Width | Yes | Yes | UI label is "Width", not "Legend size" |

5. " 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:
• 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/.png
• Reference with: ``
• Sizing: "=50%" for smaller inline images, "=60%" for examples, "=70%" for settings screenshots.
• Alt text should be descriptive, not "screenshot".

Icons

| Icon | Syntax | Usage | |------|--------|-------| | Style/brush | {icon}\brush\` | Style settings panel | | Layer settings | {icon}\app_management\ | Layer settings (9.3+/Serverless) | | Actions menu | {icon}\boxes_horizontal\ | Layer actions menu (9.0-9.2) | | Add layer | {icon}\plus_in_square\` | Add layer button |

For the legend icon, use: ``

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: elastic
• Source: elastic/elastic-docs-skills
• License: Apache-2.0
• Homepage: https://elastic.github.io/elastic-docs-skills/

Install and usage instructions live in the source repository linked above.