mdbook-plotly User Manual

This is the official user manual (English edition) for mdbook-plotly, a preprocessor that renders interactive or static Plotly charts in mdbook documentation. The manual provides comprehensive reference and usage instructions.

Note

This user manual is available in multiple languages; however, not all language versions are guaranteed to reflect the latest application updates. In case of discrepancies among different language versions, the Chinese version shall prevail.

Quick Start
Configuration Reference
- Configuration Syntax
- Configuration Options
Input Formats
- JSON Input
- Output Formats

Quick Start

This section guides you through installing mdbook-plotly, configuring your mdbook, and creating your first chart.

Installation

Using Cargo

cargo install mdbook-plotly

If you use cargo-binstall:

cargo binstall mdbook-plotly

Manual Download

Download the latest release for your platform from the Releases page and add the binary to your system's PATH.

Basic Configuration

Add the following to your book's book.toml file:

[preprocessor.plotly]
after = ["links"]

This configuration enables the default JSON5 input format. Code blocks with language plot or plotly will be processed into interactive Plotly charts.

Note

mdbook-plotly uses JSON5 syntax, which extends JSON with comments, trailing commas, unquoted object keys, single‑quoted strings, hexadecimal numbers, and multi‑line strings. This improves readability and maintainability of chart definitions.

First Chart Example

A minimal chart definition requires three top‑level fields: data, layout, and config:

```plot
{
    layout: {
        title: "Test Chart",
    },
    data: [{
        type: "pie",
        values: [10, 20, 30, 40],
    }],
    config: {
        static_plot: true,
    }
}
```

This example:

Sets the chart title to "Test Chart"
Creates a pie chart with four slices
Disables interactivity (static plot)

For detailed information on available chart types, configuration options, and advanced features, refer to the sections below.

TUI Edition

Starting with v0.3.0, mdbook-plotly ships two binary variants:

Variant	Release asset name	Contents
slim (default)	`mdbook-plotly-<version>-<target>.<ext>`	The preprocessor only. `cargo install mdbook-plotly` gives you this.
full (`-tui`)	`mdbook-plotly-<version>-<target>-tui.<ext>`	The preprocessor plus an interactive TUI with self-update, a guided `book.toml` editor, and a plot generator.

The self-update tool only ever looks for assets of its own variant, so a slim binary never updates from a -tui asset. See RELEASE.md for the full asset naming rules.

Installing the Full Edition

cargo install mdbook-plotly --features tui

or download the release asset ending in -tui for your platform from the Releases page.

The `tui` Command

The full edition registers a tui subcommand. The slim edition recognizes the command and prints instructions instead of failing with "unknown subcommand".

mdbook-plotly tui [OPTIONS]

Options:

Option	Meaning
`--dry-run`	Self-update: check and report without downloading or replacing anything.
`--no-effects`	Disable the view-transition animations.
`--no-preview`	Plot generator: disable the live preview; generate only on demand.

The TUI has a welcome view and three tools:

Self-update — queries the GitHub Releases API, compares the latest tag against the running version (semver), and on confirmation downloads the matching -tui asset, verifies its .sha256, and atomically replaces the running binary. Always asks before replacing; --dry-run never downloads. Reads GITHUB_TOKEN to raise the unauthenticated API rate limit.
book.toml editor — finds book.toml by walking up from the current directory, and lets you edit the [preprocessor.plotly] keys (plus book.title) with a description and valid range for each field. It uses toml_edit so comments and formatting are preserved, shows a diff before writing, and writes atomically.
Plot generator — a questionnaire-driven way to produce chart configs without writing JSON by hand. Pick one of eight plot types, fill in the per-trace fields (name, data, type, mode, color, …), and watch a live JSON/TOML preview. A chart can hold any number of traces ([ / ] switch trace, a adds, d removes) and two extra raw-JSON5 fields let you write the config and map sections of the plot block directly. Validation flags missing required fields and bad numbers inline. c copies the result to the clipboard, s saves it to plot-<type>.json/.toml, and r restores the built-in example. The generator is fully offline: the schema is embedded in the binary, so there is nothing to fetch.

Schema Language

The plot generator's schema comes in two languages and is picked automatically, in this order:

MDBOOK_PLOTLY_LANG environment variable (zh, zh-CN, en, …)
[language] doc in the settings file (zh_CN or en)
The system locale (anything starting with zh selects the Chinese schema)

MDBOOK_PLOTLY_LANG=zh mdbook-plotly tui

docs/PLOT-SCHEMA.json (English) and docs/PLOT-SCHEMA-zh_CN.json (Chinese) are the single source of truth for the generator: field names, targets, and examples stay in sync across languages, so switching locale only changes the wording, never the generated configuration.

GitHub Proxy / Mirror

All GitHub access (self-update API and asset downloads) goes through configurable endpoints. No URL is hardcoded. Configure them with the environment, the settings file, or both:

Setting	Environment variable	Config file key	Meaning
Proxy prefix	`MDBOOK_PLOTLY_GITHUB_PROXY`	`github.proxy`	Prefix prepended to every GitHub URL (e.g. `https://ghproxy.com/`)
API base	`MDBOOK_PLOTLY_GITHUB_API`	`github.api`	Replaces `https://api.github.com`
Download base	`MDBOOK_PLOTLY_GITHUB_DOWNLOAD`	`github.download`	Replaces `https://github.com` for release assets

Settings file location (XDG): $XDG_CONFIG_HOME/mdbook-plotly/config.toml (~/Library/Application Support/mdbook-plotly/config.toml on macOS). Environment variables take precedence over the config file, which takes precedence over the defaults. Unknown keys are ignored, so future settings do not break older binaries.

# ~/.config/mdbook-plotly/config.toml
[language]
doc = "zh_CN"

[github]
proxy = "https://ghproxy.com/"

Configuration Reference

Configuration options for mdbook-plotly are specified in the [preprocessor.plotly] section of your book.toml.

Configuration Syntax

All configuration keys use kebab-case. The parser follows these rules:

Unknown keys are ignored with warnings – unrecognized configuration keys are skipped, and a warning is logged for each unknown key path, including nested keys such as preprocessor.plotly.map-eval.extra.
Type‑sensitive validation – a key with an invalid type (e.g., a string where a boolean is expected) falls back only that field or nested section to its default value, and a warning is logged.
Missing section warning – if the [preprocessor.plotly] section is absent, a warning is issued and default values are used.

Example error when an invalid enum variant is supplied:

[WARN] mdbook_plotly::preprocessor::config: Unknown config key 'preprocessor.plotly.extra' will be ignored.
[WARN] mdbook_plotly::preprocessor::config: Failed to parse config field 'preprocessor.plotly.input-type': TOML parse error ...; using default value.

Configuration Options

[preprocessor.plotly]
after = ["links"]

# Output format – determines the rendered chart format.
# Valid values: "plotly-html", "plotly-svg" (experimental)
output-type = "plotly-html"

# Input format – specifies the syntax of chart definitions.
# Valid values: "json-input", "toml-input"
input-type = "json-input"

# Whether to use offline JavaScript sources (true/false).
offline-js-sources = false

# Controls expression evaluation behavior for the `map` section.
[preprocessor.plotly.map-eval]
enabled = true
reuse-slab = true
compile-expressions = true
namespace-scope = "full-map"

Unknown keys in either section are ignored with a warning.

Note

Internally, active parser paths are being standardized around explicit ParseContext propagation together with translate_with_config!() and translate_enum_with_config!(). This keeps map.* resolution aligned with the current MapEvalConfig and avoids hidden fallback defaults in migrated code.

`map-eval` configuration

The optional map-eval section controls how expressions inside map generators such as g-number, g-number-list, and if are evaluated.

Available keys:

enabled – master switch for the map expression evaluation strategy
reuse-slab – enables reusing Slab during evaluation
compile-expressions – enables compiled fasteval execution paths when possible
namespace-scope – controls which symbols are visible to the expression namespace

Supported values for namespace-scope:

full-map – current default; preserves existing behavior and allows namespace lookup against the full map
exports-only – restricts namespace symbol lookup to map.exports.*, while explicit map references such as map.exports.value continue to work

Example:

[preprocessor.plotly.map-eval]
namespace-scope = "exports-only"

With exports-only, expressions can use values exported under map.exports as bare names, which helps separate public expression symbols from the rest of the map payload.

`map-parser-extensions` feature

The default feature set includes map-parser-extensions. When enabled, the map section accepts additional generator kinds beyond the baseline set:

baseline generators: g-number, g-number-list, g-range, g-repeat, g-linear, if, raw
extension generators: time, g-random, g-choose

If you build without map-parser-extensions, only the baseline generator set is available.

Input Formats

The input-type configuration option determines the syntax used to define charts inside plot/plotly code blocks. Currently supported values:

json-input – JSON5‑based chart definitions (recommended and currently the only supported input format)

JSON Input

This is the primary and recommended format. Charts are defined using JSON5 syntax, which extends standard JSON with comments, trailing commas, unquoted keys, and other conveniences.

Note

mdbook‑plotly implements its own deserialization logic. While the structure generally follows Plotly’s native schema, compatibility is not guaranteed, and extensions (such as map references and generators) are available. Always refer to the documented fields below for reliable usage. Missing fields can be requested via GitHub issues.

JSON Syntax and Type System

The following notation is used throughout this reference to describe expected types and optionality.

{
    // A `?` after a field name indicates the field is optional.
    data?: [
        {
            // No `?` means the field is required.
            type: "pie",
            // Some fields become required when another field has a specific value.
            // Such dependencies are noted in the documentation.
            values: [usize; usize]   // Required when `type` is `"pie"`.
        }
    ],

    layout?: {
        legend?: {
            title?: String,
            background_color?: Rgba
        }
    }
}

Basic Types

Objects – { "key": value } or { key: value } (JSON5 allows unquoted keys)
Arrays – [value1, value2, ...]; notation [T; N] means an array of N elements each of type T
Strings – "text" or 'text'; String denotes any string
Numbers – usize (non‑negative integer), isize (signed integer), f64 (floating‑point)
Booleans – true or false
Unions – "a" | "b" means the value can be either "a" or "b"
Ranges – 0..6f64 means any f64 value ≥ 0.0 and < 6.0

Common Composite Types

Rgb – "rgb(u8, u8, u8)" (e.g., "rgb(0, 0, 0)")
Rgba – "rgba(u8, u8, u8, f64)" (e.g., "rgba(0, 0, 0, 0.0)")
Color – can be one of the following:
- A named CSS color: "aliceblue"
- An RGB color: "rgb(255, 0, 0)"
- An RGBA color: "rgba(255, 0, 0, 0.5)"

Common Complex Types

The marker object controls the visual appearance of data points, including color, opacity, size, symbol shape, and color scale. This object applies to trace types that support a marker field (e.g., scatter, bar, scatterpolar, etc.).

{
    // ===== Basic visual properties =====
    // Fill color of the data points
    color?: Color,
    // Opacity from 0 (transparent) to 1 (opaque)
    opacity?: f64,
    // Uniform size of data points (pixels or interpreted according to size_mode)
    size?: usize,
    // Per‑point size array
    size_array?: [usize; usize],

    // Marker symbol shape
    symbol?: "circle" | "square" | "diamond" | "cross" | "x" | "triangle-up" | "triangle-down" | "triangle-left" | "triangle-right" | "pentagon" | "hexagon",
    // Size mode:
    //   "area"     – size value represents marker area (default)
    //   "diameter" – size value represents marker diameter
    size_mode?: "area" | "diameter",

    // ===== Size and display limits =====
    // Maximum number of displayed data points (excess points are hidden)
    max_displayed?: usize,
    // Size reference value for custom sizing (used with size_array, etc.)
    size_ref?: usize,
    // Minimum size constraint
    size_min?: usize,

    // ===== Color scale (for encoding numeric values) =====
    // Whether to auto‑compute the color scale range (cmax/cmin)
    cauto?: bool,
    // Maximum value of the color scale
    cmax?: f64,
    // Minimum value of the color scale
    cmin?: f64,
    // Midpoint of the color scale (used for diverging color bars)
    cmid?: f64,
    // Whether to automatically select the color scale
    auto_color_scale?: bool,
    // Whether to reverse the color scale
    reverse_scale?: bool,
    // Whether to display the color bar
    show_scale?: bool,
    // Color for outlier points (only effective in certain trace types)
    outlier_color?: Color,
}

Map and Generators

The map field provides a mapping table that can be referenced elsewhere in the chart definition using the map.key syntax. This allows reuse of data and generation of complex values via built-in generators.

Map values can be either raw data (any JSON value) or generator objects. Generator objects have a type field indicating the generation algorithm, plus additional parameters.

Generator Types

Map values can be either raw data (any JSON value) or generator objects. Generator objects have a type field indicating the generation algorithm, plus additional parameters.

Generator Types

All generator objects must have a type field. The following generator types are supported:

raw — Passes through data unchanged.

Parameters:

{
    type: "raw",
    data: T  // Any value to be used directly
}

Example:

{ type: "raw", data: [1, 2, 3] }

g-number-list — Generates a list of numbers by evaluating an expression for each integer in a range.

Parameters:

{
    type: "g-number-list",
    begin: usize,   // inclusive start index
    end: usize,     // exclusive end index
    expr: String    // arithmetic expression in variable `i`
}

The expression is evaluated using the fasteval library; the variable i (as f64) is available inside the expression.

Example:

{ type: "g-number-list", begin: 0, end: 3, expr: "i * 2" }
// yields [0.0, 2.0, 4.0]

g-number — Evaluates a constant arithmetic expression.

Parameters:

{
    type: "g-number",
    expr: String    // arithmetic expression (no variables)
}

Example:

{ type: "g-number", expr: "2 + 3 * 4" }
// yields 14.0

g-range — Generates an arithmetic progression of floating‑point numbers.

Parameters:

{
    type: "g-range",
    begin: f64,     // first value (inclusive)
    end: f64,       // upper bound (exclusive)
    step?: f64      // step size (default 1.0, must be positive)
}

Example:

{ type: "g-range", begin: 0.0, end: 5.0, step: 1.0 }
// yields [0.0, 1.0, 2.0, 3.0, 4.0]

g-repeat — Repeats a given value a specified number of times.

Parameters:

{
    type: "g-repeat",
    value: T,       // any JSON value
    count: usize    // number of repetitions
}

Example:

{ type: "g-repeat", value: 42.0, count: 3 }
// yields [42.0, 42.0, 42.0]

g-linear — Generates count values linearly spaced between begin and end (inclusive of both endpoints).

Parameters:

{
    type: "g-linear",
    begin: f64,
    end: f64,
    count: usize    // must be positive
}

If count is 1, the result is [begin]. Otherwise the step is (end - begin) / (count - 1).

Example:

{ type: "g-linear", begin: 0.0, end: 1.0, count: 5 }
// yields [0.0, 0.25, 0.5, 0.75, 1.0]

g-random — Generates random numbers. Can produce a single value or an array; supports integers or floats; an optional seed ensures reproducibility.

Parameters:

{
    type: "g-random",
    min: f64,           // minimum value (inclusive)
    max: f64,           // maximum value (exclusive)
    integer?: bool,     // generate integers (default false)
    seed?: u64,         // random seed (optional; same seed → same sequence)
    count?: u64         // number of values to generate (omit for a single value)
}

Example:

// Generate a single floating‑point number between 0 and 100
{ type: "g-random", min: 0, max: 100 }

// Generate 5 integers between 1 and 10 (fixed seed)
{ type: "g-random", min: 1, max: 11, integer: true, seed: 42, count: 5 }

g-choose — Randomly picks from a list of options. Can pick a single value or an array; optional seed.

Parameters:

{
    type: "g-choose",
    options: [T; usize],  // candidates (must not be empty)
    seed?: u64,           // random seed (optional)
    count?: u64           // number of picks (omit for a single pick)
}

Example:

{ type: "g-choose", options: ["red", "green", "blue", "yellow"], seed: 1, count: 3 }
// might yield ["blue", "red", "yellow"]

g-env — Reads the value of an environment variable. Useful for injecting build‑time configuration; an optional default can be provided.

Parameters:

{
    type: "g-env",
    name: String,         // environment variable name
    default?: String      // fallback when the variable is not set
}

If the variable is not set and no default is given, an error is raised.

Example:

{ type: "g-env", name: "MAPBOX_TOKEN", default: "" }
// reads $MAPBOX_TOKEN, returns "" if not set

g-join — Joins an array of strings into a single string using a separator.

Parameters:

{
    type: "g-join",
    values: [String; usize],  // strings to join
    separator?: String        // separator (default: empty string)
}

Example:

{ type: "g-join", values: ["a", "b", "c"], separator: ", " }
// yields "a, b, c"

if — Conditionally selects between two values based on an arithmetic expression.

Parameters:

{
    type: "if",
    condition: String,    // arithmetic expression that evaluates to a number
    true: T,              // value used when condition ≠ 0.0
    false: T              // value used when condition = 0.0
}

The condition is evaluated using the fasteval library; no variables are available. Comparison operators (e.g., 2 > 1) yield 1.0 (true) or 0.0 (false).

Example:

{ type: "if", condition: "2 > 1", true: [1,2,3], false: [4,5,6] }
// yields [1,2,3] because 2 > 1 evaluates to 1.0 (non‑zero)

time — Generates a sequence of timestamps between two time points at a specified interval.

Parameters:

{
    type: "time",
    start: String,        // start time string
    end: String,          // end time string
    interval: String,     // interval (e.g., "1d", "2h", "30m")
    format?: String       // optional output format (strftime syntax, default RFC 3339)
}

Supported time string formats: RFC 3339, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DD. Relative times are also supported: now, now+1d, now-2h, etc.

Supported interval units: s (seconds), m (minutes), h (hours), d (days), w (weeks). Units can be combined, e.g., "1d12h30m".

Example:

{ type: "time", start: "2026-01-01", end: "2026-01-03", interval: "1d" }
// yields ["2026-01-01T00:00:00+00:00", "2026-01-02T00:00:00+00:00", "2026-01-03T00:00:00+00:00"]

{ type: "time", start: "now", end: "now+3d", interval: "1d", format: "%Y-%m-%d" }
// yields [today, tomorrow, day after tomorrow, 3 days from now] formatted as "YYYY-MM-DD"

Using the Map

Map entries are referenced elsewhere by prefixing the key with map.. For example, if the map contains a key myrange, you can refer to it as "map.myrange" in any field that accepts a DataPack<T> (most array and numeric fields).

Complete example:

{
    map: {
        xs: { type: "g-linear", begin: 0, end: 10, count: 5 },
        ys: { type: "g-number-list", begin: 0, end: 5, expr: "i * i" }
    },
    data: [{
        type: "scatter",
        x: "map.xs",
        y: "map.ys"
    }]
}

Since most of them are compatible with DataPack<T>, only the incompatible ones are given here:

Any type field (usually hard-coded in the code, so it is not recommended to change)
Primitive generators in Map

Also note that the generator is lazily loaded each time it is processed, and the same generator does not share data between different fields, so it will be re-evaluated each time a Map is used.

If you find that some items are not given above, but do not support Map, please submit an Issue, and we will solve it.

Chart Main Format

{
    // Build a mapping table for populating mappings in the sections below.
    map?: Map,

    // Chart layout configuration
    layout?: Layout,

    // Chart data
    data?: [Data; usize],

    // Chart configuration
    config?: Configuration,
}

Layout Format

layout: {
    // The chart title
    title?: String,
    // Whether to display the legend
    show_legend?: bool,
    // Chart height
    // NOTE: The chart can auto-resize; modifying this may cause layout issues on some devices.
    height?: usize,
    // Chart width
    // NOTE: The chart can auto-resize; modifying this may cause layout issues on some devices.
    width?: usize,
    // Chart colorway
    // For example, a pie chart requires multiple colors for its slices;
    // the program picks colors sequentially from this colorway.
    colorway?: [Color; usize],
    // Chart background color
    plot_background_color?: Color,
    // Separators
    separators?: String,
    // Whether to enable automatic size adjustment (default true)
    auto_size?: bool,
    // Paper background colour (distinct from plot_background_color)
    paper_background_color?: Color,

    // ===== Phase 1 fields =====

    // Bar gap (0~1), controls spacing between bars in the same group
    bar_gap?: f64,
    // Bar group gap (0~1), controls spacing between bar groups
    bar_group_gap?: f64,
    // Box gap (0~1), controls spacing between boxes in the same group
    box_gap?: f64,
    // Box group gap (0~1), controls spacing between box groups
    box_group_gap?: f64,

    // Hover mode
    // "x": show only data aligned with x coordinate
    // "y": show only data aligned with y coordinate
    // "closest": show closest data point
    // "false": disable hover
    // "x unified": unified display for x-aligned data
    // "y unified": unified display for y-aligned data
    hover_mode?: "x" | "y" | "closest" | "false" | "x unified" | "y unified",

    // Drag mode
    // "zoom": box select zoom
    // "pan": pan
    // "select": box select
    // "lasso": lasso select
    // "orbit": 3D orbit rotation
    // "turntable": 3D turntable rotation
    // "false": disabled
    drag_mode?: "zoom" | "pan" | "select" | "lasso" | "orbit" | "turntable" | "false",

    // Click mode
    // "event": fire click events
    // "select": trigger selection
    // "none": disabled
    click_mode?: "event" | "select" | "none",

    // Global font settings
    font?: {
        // Font family (e.g., "Arial", "sans-serif")
        family?: String,
        // Font size (pixels)
        size?: usize,
        // Font color
        color?: Color,
    },

    // Color axis configuration
    coloraxis?: {
        // Color scale minimum
        cmin?: f64,
        // Color scale maximum
        cmax?: f64,
        // Color scale midpoint (for diverging color bars)
        cmid?: f64,
        // Whether to auto-select the color scale
        auto_color_scale?: bool,
        // Whether to reverse the color scale
        reverse_scale?: bool,
        // Whether to display the color bar
        show_scale?: bool,
    },

    // ===== Axis Configuration =====
    // Default axes: xaxis, yaxis
    xaxis?: Axis,
    yaxis?: Axis,
    // Additional named axes: up to 8 (xaxis2~xaxis8, yaxis2~yaxis8)
    xaxis2?: Axis,
    xaxis3?: Axis,
    xaxis4?: Axis,
    xaxis5?: Axis,
    xaxis6?: Axis,
    xaxis7?: Axis,
    xaxis8?: Axis,
    yaxis2?: Axis,
    yaxis3?: Axis,
    yaxis4?: Axis,
    yaxis5?: Axis,
    yaxis6?: Axis,
    yaxis7?: Axis,
    yaxis8?: Axis,

    // Legend configuration
    legend?: {
        // Background color
        background_color?: Color,
        // Border color
        border_color?: Color,
        // Border width
        border_width?: usize,
        // X-axis extent
        x?: f64,
        // Y-axis extent
        y?: f64,
        // Gap between trace groups
        trace_group_gap?: usize,
        // Title
        title?: String,
        // Width of each legend item (pixels)
        item_width?: usize,

        // Trace display order within the legend
        // "normal": natural order
        // "reversed": reversed order
        // "grouped": grouped by trace group
        // "reversed+grouped": reversed and grouped
        trace_order?: "normal" | "reversed" | "grouped" | "reversed+grouped",

        // Legend item sizing mode
        // "trace": sized per trace
        // "constant": constant width
        item_sizing?: "trace" | "constant",

        // Single-click behaviour on legend items
        // "toggle": toggle the trace
        // "toggleothers": toggle all other traces
        // "false": no action
        item_click?: "toggle" | "toggleothers" | "false",

        // Double-click behaviour on legend items (same values as item_click)
        item_double_click?: "toggle" | "toggleothers" | "false",

        // Vertical alignment of legend text
        // "top", "middle", "bottom"
        valign?: "top" | "middle" | "bottom",

        // Click behaviour on legend groups
        // "toggleitem": toggle all items in the group
        // "togglegroup": toggle the group
        group_click?: "toggleitem" | "togglegroup",
    },

    // Chart margin configuration
    margin?: {
        // Left margin width
        left?: usize,
        // Right margin width
        right?: usize,
        // Top margin width
        top?: usize,
        // Bottom margin width
        bottom?: usize,
        // Uniform margin width
        // NOTE: This option overrides all individual margin settings.
        // Not recommended to use together with individual margin settings.
        pad?: usize,
        // Auto-expand
        auto_expand?: bool
    },
}

Axis Reference

The Axis object configures x and y axes. Supports the default axes (xaxis/yaxis) as well as up to 8 additional named axes (xaxis2–xaxis8/yaxis2–yaxis8).

All Axis fields support DataPack map references (e.g. "map.my_range").

{
    // Axis title
    title?: String,
    // Axis type
    // "linear": linear scale (default)
    // "log": logarithmic scale
    // "date": date/time axis
    // "category": categorical axis
    // "multicategory": multi-level categorical axis
    type?: "-" | "linear" | "log" | "date" | "category" | "multicategory",

    // Axis range [min, max]
    // Use null for open bounds, e.g. [0, null] = from 0 upward
    // Date axes accept date strings, e.g. ["2024-01-01", "2024-01-10"]
    range?: [f64; 2],

    // Axis domain on the canvas (0~1)
    // e.g. [0, 0.5] means the axis occupies the left half
    domain?: [f64; 2],

    // The axis this one is anchored to (e.g. "y", "y2", "free")
    anchor?: String,
    // Show/hide the axis
    visible?: bool,
    // Whether to auto-adjust margins
    auto_margin?: bool,

    // Grid & line styling
    show_grid?: bool,       // Show grid lines
    show_line?: bool,       // Show axis line
    show_tick_labels?: bool,// Show tick labels
    zero_line?: bool,       // Show zero line
    grid_color?: Color,     // Grid line color
    line_color?: Color,     // Axis line color
    grid_width?: f64,       // Grid line width
    line_width?: f64,       // Axis line width
    color?: Color,          // Tick color

    // Tick configuration
    tick_prefix?: String,   // Tick label prefix
    tick_suffix?: String,   // Tick label suffix
    tick_format?: String,   // Tick format (d3-format syntax)
    tick_angle?: f64,       // Tick label rotation angle
    tick0?: f64,            // Starting tick value
    dtick?: f64,            // Tick step
    nticks?: usize,         // Number of ticks
    hover_format?: String,  // Hover tooltip format

    // Category axis
    category_array?: [String; usize],   // Category order list
    category_order?: "trace" | "category-ascending" | "category-descending"
                    | "array" | "total-ascending" | "total-descending"
                    | "min-ascending" | "min-descending"
                    | "max-ascending" | "max-descending"
                    | "sum-ascending" | "sum-descending"
                    | "mean-ascending" | "mean-descending"
                    | "median-ascending" | "median-descending",

    // Axis overlay (for dual-axis charts)
    // e.g. yaxis2.overlaying: "y" means y2 overlays on y
    overlaying?: String,
    // Axis side
    side?: "bottom" | "top" | "left" | "right",
    // Axis position offset
    position?: f64,
    // Axis layer
    // "above traces": drawn above data
    // "below traces": drawn below data
    layer?: String,

    // Fixed range (disable zoom/pan)
    fixed_range?: bool,
    // Scale anchor (e.g., y axis scales anchored to x axis)
    scale_anchor?: String,
    // Scale ratio
    scale_ratio?: f64,
}

Dual Y-Axis Example

{
    layout: {
        xaxis: {
            title: "Time",
        },
        yaxis: {
            title: "Left Axis",
            side: "left",
        },
        yaxis2: {
            title: "Right Axis",
            overlaying: "y",
            side: "right",
        },
    },
    data: [
        { type: "scatter", x: [1,2,3], y: [4,5,6] },
        { type: "scatter", x: [1,2,3], y: [10,20,30], yaxis: "y2" },
    ]
}

Config Format

config: {
    // Static chart (disables interactivity)
    static_plot?: bool,
    // Math typesetting
    // Effective when MathJax is present on the page
    typeset_math?: bool,
    // Whether the chart is editable
    editable?: bool,
    // Whether auto-sizing is enabled
    autosizable?: bool,
    // Whether to fill the screen
    // NOTE: Only effective when `autosizable` is `true`.
    fill_frame?: bool,
    // Margin width
    // NOTE: Only effective when `autosizable` is `true`.
    frame_margins?: f64,
    // Whether mouse scroll wheel or two-finger pinch zoom is enabled
    // NOTE: Disabled by default for Cartesian subplots; enabled by default for others.
    scroll_zoom?: bool,
    // Show drag handles for panning/zooming on Cartesian axes
    show_axis_drag_handles?: bool,
    // Show range input boxes when panning/zooming
    // NOTE: Only effective when `show_axis_drag_handles` is `true`.
    show_axis_range_entry_boxes?: bool,
    // Whether to show tips for interactive charts
    show_tips?: bool,
    // Whether to display a link to Chart Studio Cloud in the bottom-right corner of the chart
    show_link?: bool,
    // Whether to include data linked only to Chart Studio Cloud files
    // NOTE: Only effective when `show_link` is `true`.
    send_data?: bool,
    // Available delay interval for certain double-click actions
    double_click_delay?: usize,
    // Mapbox access token
    mapbox_access_token?: String,
    // Set the length of the undo/redo queue
    queue_length?: usize,
    // Whether to display the Plotly logo at the end of the mode bar
    display_logo?: bool,
    // Watermark the image with a company logo
    watermark?: bool,

    // Controls when the modebar appears
    // "hover": only show on hover
    // "true": always show (default)
    // "false": never show
    display_mode_bar?: "hover" | "true" | "false",

    // Double-click behaviour
    // "false": no action
    // "reset": reset the chart view
    // "autosize": autosize
    // "reset+autosize": reset and autosize
    double_click?: "false" | "reset" | "autosize" | "reset+autosize",

    // Whether to show an "Edit in Chart Studio" link (alias for show_link)
    show_edit_in_chart_studio?: bool,
}

Data-bar

bar can be a Data entry. This Data will be rendered as a bar chart.

{
    type: "bar",

    // X-axis coordinate data
    x: [f64; usize],
    // Y-axis coordinate data
    y: [f64; usize],

    // Unique identifier for each data point
    ids?: [String; usize],
    // Uniform offset for all bars relative to their default positions
    offset?: f64,
    // Individual offset for each bar
    offset_array?: [f64; usize],
    // Uniform text displayed on the bars
    text?: String,
    // Individual text for each bar
    text_array?: [String; usize],
    // Text template with variable substitution (e.g., "%{x}", "%{y}")
    text_template?: String,
    // Hover label template
    hover_template?: String,
    // Individual hover template for each data point
    hover_template_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each data point
    hover_text_array?: [String; usize],
    // Trace name, displayed in the legend and hover info
    name?: String,
    // Opacity, ranging from 0 (fully transparent) to 1 (fully opaque)
    opacity?: f64,
    // Binds this trace to a specific x-axis (for multi-axis charts, e.g., "x2")
    x_axis?: String,
    // Binds this trace to a specific y-axis (for multi-axis charts, e.g., "y2")
    y_axis?: String,
    // Alignment group identifier; bars in the same group are aligned along the axis
    alignment_group?: String,
    // Offset group identifier; bars in the same group share offset space
    offset_group?: String,
    // Whether to clip content that extends beyond the axis range
    clip_on_axis?: bool,
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Legend group identifier; traces in the same group are grouped together in the legend
    legend_group?: String,
    // Bar width (in data coordinate units)
    width?: f64,
    // Rotation angle for text on the bars (in degrees)
    text_angle?: f64,
    // Bar orientation: "v" for vertical bar chart, "h" for horizontal bar chart
    orientation?: "v" | "h",
    // Controls the visual appearance of data points
    marker?: Marker,
}

Data-candlestick

candlestick can be a Data entry. This Data will be rendered as a candlestick chart—the most common representation of price movements in financial visualization.

{
    type: "candlestick",

    // X-axis data (typically date strings, e.g., "2024-01-15")
    x: [String; usize],
    // Opening price
    open: [f64; usize],
    // Highest price
    high: [f64; usize],
    // Lowest price
    low: [f64; usize],
    // Closing price (close > open indicates a bullish candle; otherwise bearish)
    close: [f64; usize],

    // Trace name, displayed in the legend and hover info
    name?: String,
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Legend group identifier
    legend_group?: String,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Uniform text displayed on data points
    text?: String,
    // Individual text for each data point
    text_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each data point
    hover_text_array?: [String; usize],
    // Whisker width, ranging from 0 to 1 (0 = no whisker tick, 1 = same width as the body)
    whisker_width?: f64,
    // Binds this trace to a specific x-axis (for multi-axis charts, e.g., "x2")
    x_axis?: String,
    // Binds this trace to a specific y-axis (for multi-axis charts, e.g., "y2")
    y_axis?: String,
    // Visibility control
    // "true": visible (default)
    // "false": hidden
    // "legendonly": not drawn but shown in the legend
    visible?: "true" | "false" | "legendonly",
}

Data-density_mapbox

densitymapbox can be a Data entry. This Data will be rendered as a density heatmap on a map.

Note

Using this trace requires configuring the corresponding mapbox object in Layout.

{
    type: "density_mapbox",

    // Latitude of each data point
    lat: [f64; usize],
    // Longitude of each data point
    lon: [f64; usize],
    // Weight value for each data point, determining density intensity
    z: [f64; usize],

    // Whether to show this trace in the legend
    show_legend?: bool,
    // Trace name, displayed in the legend and hover info
    name?: String,
    // Legend group identifier; traces in the same group are grouped together in the legend
    legend_group?: String,
    // Legend sort priority; lower values appear first
    legend_rank?: usize,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Influence radius for each data point (in pixels, default 30)
    radius?: u8,
    // Map zoom level
    zoom?: u8,
    // Whether to automatically compute zmin and zmax from the data
    zauto?: bool,
    // Lower bound for color mapping
    zmin?: f64,
    // Midpoint for color mapping
    zmid?: f64,
    // Upper bound for color mapping
    zmax?: f64,
    // Specifies the mapbox subplot to use (e.g., "mapbox", "mapbox2")
    subplot?: String,
}

Data-histogram

histogram can be a Data entry. This Data will be rendered as a histogram.

{
    type: "histogram",

    // X-axis data (at least one of x and y must be provided)
    // Providing only x creates a histogram along the horizontal axis
    x?: [f64; usize],
    // Y-axis data (at least one of x and y must be provided)
    // Providing only y creates a histogram along the vertical axis
    // Providing both x and y creates a bivariate histogram
    y?: [f64; usize],

    // Trace name, displayed in the legend and hover info
    name?: String,
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Legend group identifier
    legend_group?: String,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Uniform text displayed on the bars
    text?: String,
    // Individual text for each bar
    text_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each bar
    hover_text_array?: [String; usize],
    // Hover label template
    hover_template?: String,
    // Individual hover template for each bar
    hover_template_array?: [String; usize],
    // Whether to automatically determine the number of bins for the x-axis
    auto_bin_x?: bool,
    // Number of bins for the x-axis (effective when auto_bin_x is false)
    n_bins_x?: usize,
    // Whether to automatically determine the number of bins for the y-axis
    auto_bin_y?: bool,
    // Number of bins for the y-axis (effective when auto_bin_y is false)
    n_bins_y?: usize,
    // Alignment group identifier; bars in the same group are aligned along the axis
    alignment_group?: String,
    // Offset group identifier; bars in the same group share offset space
    offset_group?: String,
    // Bin group identifier; histograms in the same group share bin boundaries
    bin_group?: String,
    // Binds this trace to a specific x-axis (for multi-axis charts, e.g., "x2")
    x_axis?: String,
    // Binds this trace to a specific y-axis (for multi-axis charts, e.g., "y2")
    y_axis?: String,
    // Bar orientation: "v" for vertical, "h" for horizontal
    orientation?: "v" | "h",
    // Histogram aggregation function, determining how values within each bin are computed
    // "count": count (default)
    // "sum": sum
    // "avg": average
    // "min": minimum
    // "max": maximum
    hist_func?: "count" | "sum" | "avg" | "min" | "max",
    // Histogram normalization mode
    // "": no normalization (default)
    // "percent": expressed as a percentage
    // "probability": expressed as probability (sums to 1)
    // "density": probability density (area integrates to 1)
    // "probability density": probability density (similar to density)
    hist_norm?: "" | "percent" | "probability" | "density" | "probability density",
    // Controls the visual appearance of data points
    marker?: Marker,
}

Data-ohlc

ohlc can be a Data entry. This Data will be rendered as an OHLC chart, commonly used for financial stock trend analysis.

{
    type: "ohlc",

    // X-axis data (typically date strings, e.g., "2024-01-15")
    x: [String; usize],
    // Opening price
    open: [f64; usize],
    // Highest price
    high: [f64; usize],
    // Lowest price
    low: [f64; usize],
    // Closing price (close > open indicates an uptrend; otherwise a downtrend)
    close: [f64; usize],

    // Trace name, displayed in the legend and hover info
    name?: String,
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Legend group identifier
    legend_group?: String,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each data point
    hover_text_array?: [String; usize],
    // Width of the top and bottom tick marks, ranging from 0 to 0.5
    tick_width?: f64,
    // Visibility control
    // "true": visible (default)
    // "false": hidden
    // "legendonly": not drawn but shown in the legend
    visible?: "true" | "false" | "legendonly",
}

Data-image

image can be a Data entry. This Data will be rendered as a pixel image, supporting direct image display via a 2D pixel array within a Cartesian coordinate system.

{
    type: "image",

    // Image pixel data
    z: [[Rgb; unsize]; unsize],

    // Opacity, ranging from 0 (fully transparent) to 1 (fully opaque)
    opacity?: f64,
    // Trace name, displayed in the legend and hover info
    name?: String,
    // Legend sort priority; lower values appear first
    legend_rank?: usize,
    // Uniform text displayed on the image
    text?: String,
    // Individual text for each pixel
    text_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each pixel
    hover_text_array?: [String; usize],
    // Hover label template
    hover_template?: String,
    // Individual hover template for each pixel
    hover_template_array?: [String; usize],
    // Image source specified via data URI (e.g., "data:image/png;base64,...")
    // When set, z data will be ignored
    source?: String,
    // X coordinate of the image's bottom-left corner (default 0)
    x0?: f64,
    // Pixel spacing in the x direction (default 1)
    dx?: f64,
    // Y coordinate of the image's bottom-left corner (default 0)
    y0?: f64,
    // Pixel spacing in the y direction (default 1)
    dy?: f64,
    // Binds this trace to a specific x-axis (for multi-axis charts, e.g., "x2")
    x_axis?: String,
    // Binds this trace to a specific y-axis (for multi-axis charts, e.g., "y2")
    y_axis?: String,
    // Unique identifier for each data point
    ids?: [String; usize],
    // Metadata, accessible in templates via %{meta}
    meta?: String,
    // Image smoothing algorithm
    // "fast": fast smoothing
    // "false": no smoothing (shows raw pixels)
    z_smooth?: "fast" | "false",
}

Data-pie

pie can be a Data entry. This Data will be rendered as a pie chart.

{
    type: "pie",

    // Numeric value for each sector
    values: [f64; usize],

    // Whether to auto-adjust margins to prevent text clipping
    automargin?: bool,
    // Delta value between adjacent labels (used with label0)
    dlabel?: f64,
    // Proportion of the center hole, ranging from 0 to 1 (0 = full pie, >0 = donut chart)
    hole?: f64,
    // Hover label template
    hover_template?: String,
    // Individual hover template for each sector
    hover_template_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each sector
    hover_text_array?: [String; usize],
    // Unique identifier for each sector
    ids?: [String; usize],
    // Starting label value (used with dlabel to auto-generate labels)
    label0?: f64,
    // Label text for each sector
    labels?: [String; usize],
    // Legend group identifier
    legend_group?: String,
    // Legend sort priority; lower values appear first
    legend_rank?: usize,
    // Trace name, displayed in the legend and hover info
    name?: String,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Metadata, accessible in templates via %{meta}
    meta?: String,
    // Whether to sort sectors by value
    sort?: bool,
    // Text position source identifier
    text_position_src?: String,
    // Individual text position source identifier for each sector
    text_position_src_array?: [String; usize],
    // Uniform text displayed on sectors
    text?: String,
    // Individual text for each sector
    text_array?: [String; usize],
    // Controls the displayed information content (e.g., "percent", "label", "value", or combinations)
    text_info?: String,
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Starting rotation angle for the pie chart (in degrees; default starts from the 12 o'clock position)
    rotation?: f64,
    // Pull distance for sectors, ranging from 0 to 1 (used to highlight a specific sector)
    pull?: f64,
    // Sector arrangement direction
    direction?: "clockwise" | "counterclockwise",
    // Controls the visual appearance of data points
    marker?: Marker,
}

Data-sankey

sankey can be a Data entry. This Data will be rendered as a Sankey diagram, used for visualizing flow relationships between nodes.

{
    type: "sankey",

    // Node configuration
    node?: {
        // Node colors
        color?: [Color; usize],
        // Padding between nodes (in pixels)
        pad?: f64,
        // Node thickness (in pixels)
        thickness?: f64,
    },

    // Trace name, displayed in the legend and hover info
    name?: String,
    // Whether the trace is visible
    visible?: bool,
    // Value format string (d3-format syntax, e.g., ".3f" for 3 decimal places)
    value_format?: String,
    // Value suffix text (unit, e.g., "TWh", "$")
    value_suffix?: String,
    // Diagram orientation: "v" for vertical, "h" for horizontal
    orientation?: "v" | "h",
    // Node arrangement mode
    // "snap": snap to grid (default)
    // "perpendicular": perpendicular arrangement
    // "freeform": free layout (draggable)
    // "fixed": fixed position (not draggable)
    arrangement?: "snap" | "perpendicular" | "freeform" | "fixed",
}

Data-scatter_geo

scatter_geo can be a Data entry. This Data will be rendered as a geographic scatter plot, drawn on a geographic coordinate system.

{
    type: "scatter_geo",

    // Latitude of each data point
    lat: [f64; usize],
    // Longitude of each data point
    lon: [f64; usize],

    // Unique identifier for each data point
    ids?: [String; usize],
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Trace name, displayed in the legend and hover info
    name?: String,
    // Legend group identifier
    legend_group?: String,
    // Legend sort priority; lower values appear first
    legend_rank?: usize,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Uniform text displayed on data points
    text?: String,
    // Individual text for each data point
    text_array?: [String; usize],
    // Text template with variable substitution (e.g., "%{lat}", "%{lon}")
    text_template?: String,
    // Individual text template for each data point
    text_template_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each data point
    hover_text_array?: [String; usize],
    // Hover label template
    hover_template?: String,
    // Individual hover template for each data point
    hover_template_array?: [String; usize],
    // Whether to connect gaps between missing data points
    connect_gaps?: bool,
    // Specifies the geo subplot to use (e.g., "geo", "geo2")
    subplot?: String,
    // Controls the layer drawing order for this trace
    below?: String,
    // Drawing mode, determining how data points are rendered
    // "lines": lines
    // "markers": scatter markers
    // "text": text only
    // "linesmarkers": lines + markers
    // "linestext": lines + text
    // "markerstext": markers + text
    // "linemarkerstext": lines + markers + text
    // "none": hidden
    mode?: "lines" | "markers" | "text" | "linesmarkers" | "linestext" | "markerstext" | "linemarkerstext" | "none",
    // Controls the visual appearance of data points
    marker?: Marker,
}

Data-scatter_mapbox

scatter_mapbox can be a Data entry. This Data will be rendered as a Mapbox scatter plot.

Note

Using this trace requires configuring the corresponding mapbox object in Layout.

{
    type: "scatter_mapbox",

    // Latitude of each data point
    lat: [f64; usize],
    // Longitude of each data point
    lon: [f64; usize],

    // Unique identifier for each data point
    ids?: [String; usize],
    // List of selected data point indices
    selected_points?: [usize; usize],
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Trace name, displayed in the legend and hover info
    name?: String,
    // Legend group identifier
    legend_group?: String,
    // Legend sort priority; lower values appear first
    legend_rank?: usize,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Uniform text displayed on data points
    text?: String,
    // Individual text for each data point
    text_array?: [String; usize],
    // Text template with variable substitution (e.g., "%{lat}", "%{lon}")
    text_template?: String,
    // Individual text template for each data point
    text_template_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each data point
    hover_text_array?: [String; usize],
    // Hover label template
    hover_template?: String,
    // Individual hover template for each data point
    hover_template_array?: [String; usize],
    // Specifies the mapbox subplot to use (e.g., "mapbox", "mapbox2")
    subplot?: String,
    // Controls the layer drawing order for this trace
    below?: String,
    // Metadata, accessible in templates via %{meta}
    meta?: String,
    // Drawing mode, determining how data points are rendered
    // "lines": lines
    // "markers": scatter markers
    // "text": text only
    // "linesmarkers": lines + markers
    // "linestext": lines + text
    // "markerstext": markers + text
    // "linemarkerstext": lines + markers + text
    // "none": hidden
    mode?: "lines" | "markers" | "text" | "linesmarkers" | "linestext" | "markerstext" | "linemarkerstext" | "none",
    // Controls the visual appearance of data points
    marker?: Marker,
}

Data-scatter_polar

scatter_polar can be a Data entry. This Data will be rendered as a scatter plot in polar coordinates.

{
    type: "scatter_polar",

    // Angular coordinates (degrees unless layout.polar.angularaxis.thetaunit is overridden)
    theta: [f64; usize],
    // Radial coordinates
    r: [f64; usize],

    // Trace name, displayed in legend and hover info
    name?: String,
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Legend group identifier
    legend_group?: String,
    // Opacity, from 0 (transparent) to 1 (opaque)
    opacity?: f64,
    // Uniform text displayed on data points
    text?: String,
    // Per-point text
    text_array?: [String; usize],
    // Uniform hover text
    hover_text?: String,
    // Per-point hover text
    hover_text_array?: [String; usize],
    // Hover label template
    hover_template?: String,
    // Per-point hover template
    hover_template_array?: [String; usize],
    // Polar subplot to use (e.g. "polar", "polar2")
    subplot?: String,
    // Whether to connect gaps between missing data points
    connect_gaps?: bool,
    // Reference start value for radial coordinates (used to map array indices to radial distance)
    r0?: f64,
    // Radial step (used with r0)
    dr?: f64,
    // Reference start value for angular coordinates (degrees)
    theta0?: f64,
    // Angular step (degrees)
    dtheta?: f64,
    // Fill style
    // "tozeroy": fill to r=0
    // "tozerox": fill to theta=0
    // "tonexty": fill to next trace's r values
    // "tonextx": fill to next trace's theta values
    // "toself": fill enclosed area
    // "tonext": fill to next trace
    // "none": no fill
    fill?: "tozeroy" | "tozerox" | "tonexty" | "tonextx" | "toself" | "tonext" | "none",
    // Drawing mode
    // "lines": lines only
    // "markers": markers only
    // "text": text only
    // "linesmarkers": lines + markers
    // "linestext": lines + text
    // "markerstext": markers + text
    // "linemarkerstext": lines + markers + text
    // "none": hidden
    mode?: "lines" | "markers" | "text" | "linesmarkers" | "linestext" | "markerstext" | "linemarkerstext" | "none",
    // Visibility control
    // "true": visible (default)
    // "false": hidden
    // "legendonly": not drawn but shown in legend
    visible?: "true" | "false" | "legendonly",
    // Controls the visual appearance of data points
    marker?: Marker,
}

Data-scatter

scatter can be a Data entry. This Data will be rendered as a filled area chart.

{
    type: "scatter",

    // X-axis coordinate data
    x: [f64; usize],
    // Y-axis coordinate data
    y: [f64; usize],

    // Whether to enable WebGL rendering (can significantly improve performance with large datasets)
    web_gl_mode?: bool,
    // X-axis starting value (used with dx to auto-generate x coordinates at linear intervals)
    x0?: f64,
    // X-axis step size
    dx?: f64,
    // Y-axis starting value (used with dy to auto-generate y coordinates at linear intervals)
    y0?: f64,
    // Y-axis step size
    dy?: f64,
    // Unique identifier for each data point
    ids?: [String; usize],
    // Uniform text displayed on data points
    text?: String,
    // Individual text for each data point
    text_array?: [String; usize],
    // Text template with variable substitution (e.g., "%{x}", "%{y}")
    text_template?: String,
    // Hover label template
    hover_template?: String,
    // Individual hover template for each data point
    hover_template_array?: [String; usize],
    // Uniform text displayed on hover
    hover_text?: String,
    // Individual hover text for each data point
    hover_text_array?: [String; usize],
    // Trace name, displayed in the legend and hover info
    name?: String,
    // Opacity, ranging from 0 to 1
    opacity?: f64,
    // Metadata, accessible in templates via %{meta}
    meta?: String,
    // Binds this trace to a specific x-axis (for multi-axis charts, e.g., "x2")
    x_axis?: String,
    // Binds this trace to a specific y-axis (for multi-axis charts, e.g., "y2")
    y_axis?: String,
    // Stack group identifier; traces in the same group will be stacked together
    stack_group?: String,
    // Whether to clip content that extends beyond the axis range
    clip_on_axis?: bool,
    // Whether to connect gaps between missing data points (NaN / null)
    connect_gaps?: bool,
    // Fill area color
    fill_color?: Rgba,
    // Whether to show this trace in the legend
    show_legend?: bool,
    // Legend group identifier; traces in the same group are grouped together in the legend
    legend_group?: String,
    // Fill area type
    // "tozeroy": fill to y=0
    // "tozerox": fill to x=0
    // "tonexty": fill to the next trace's y values
    // "tonextx": fill to the next trace's x values
    // "toself": fill the enclosed area itself
    // "tonext": fill to the next trace
    // "none": no fill
    fill?: "tozeroy" | "tozerox" | "tonexty" | "tonextx" | "toself" | "tonext" | "none",
    // Drawing mode, determining how data points are rendered
    // "lines": line chart
    // "markers": scatter markers
    // "text": text only
    // "linesmarkers": lines + markers
    // "linestext": lines + text
    // "markerstext": markers + text
    // "linemarkerstext": lines + markers + text
    // "none": hidden
    mode?: "lines" | "markers" | "text" | "linesmarkers" | "linestext" | "markerstext" | "linemarkerstext" | "none",
    // Controls the visual appearance of data points
    marker?: Marker,
}

Data-table

table can be a Data entry. This Data will be rendered as a table.

{
    type: "table",

    // Header data; each inner array represents the header values for one column
    header_values: [[String; usize]; usize],
    // Cell data; each inner array represents the data values for one column
    // The number of values in each column must match the header
    cells_values: [[String; usize]; usize],

    // Trace name, displayed in the legend and hover info
    name?: String,
    // Column width ratio (proportionally fills available width)
    column_width?: f64,
    // Rendering order of data columns (e.g., [2, 0, 1] means the original column 0 is rendered as the 3rd column)
    column_order?: [usize; usize],
    // Visibility control
    // "true": visible (default)
    // "false": hidden
    // "legendonly": not drawn but shown in the legend
    visible?: "true" | "false" | "legendonly",
}

Data-box

box can be a Data entry. This Data will be rendered as a box plot.

{
    type: "box",
    y?: [f64; usize],
    x?: [f64; usize],
    name?: String,
    opacity?: f64,
    ids?: [String; usize],
    width?: usize,
    text?: String,
    text_array?: [String; usize],
    hover_text?: String,
    hover_text_array?: [String; usize],
    hover_template?: String,
    hover_template_array?: [String; usize],
    x_axis?: String,
    y_axis?: String,
    alignment_group?: String,
    offset_group?: String,
    show_legend?: bool,
    legend_group?: String,
    fill_color?: Color,
    notched?: bool,
    notch_width?: f64,
    whisker_width?: f64,
    q1?: [f64; usize],
    median?: [f64; usize],
    q3?: [f64; usize],
    upper_fence?: [f64; usize],
    lower_fence?: [f64; usize],
    notch_span?: [f64; usize],
    mean?: [f64; usize],
    standard_deviation?: [f64; usize],
    point_pos?: f64,
    jitter?: f64,
    orientation?: "v" | "h",
    box_mean?: "true" | "false" | "sd",
    box_points?: "all" | "outliers" | "suspectedoutliers" | "false",
    quartile_method?: "linear" | "exclusive" | "inclusive",
    hover_on?: "points" | "boxes" | "boxes+points",
    marker?: Marker,
}

Data-contour

contour can be a Data entry. This Data will be rendered as a contour plot.

{
    type: "contour",
    z: [[f64; usize]; usize],
    x?: [f64; usize],
    y?: [f64; usize],
    x0?: f64,
    dx?: f64,
    y0?: f64,
    dy?: f64,
    opacity?: f64,
    n_contours?: usize,
    connect_gaps?: bool,
    hover_on_gaps?: bool,
    show_legend?: bool,
    transpose?: bool,
    auto_contour?: bool,
    auto_color_scale?: bool,
    reverse_scale?: bool,
    show_scale?: bool,
    zauto?: bool,
    fill_color?: Color,
    contours?: {
        start?: f64,
        end?: f64,
        size?: f64,
        coloring?: "fill" | "heatmap" | "lines" | "none",
    },
    line?: Line,
    color_bar?: ColorBar,
    color_scale?: "greys" | "ylgnbu" | "greens" | "ylorrd" | "bluered" | "rdbu" | "reds" | "blues" | "picnic" | "rainbow" | "portland" | "jet" | "hot" | "blackbody" | "earth" | "electric" | "viridis" | "cividis",
}

Data-heatmap

heatmap can be a Data entry. This Data will be rendered as a heat map.

{
    type: "heatmap",
    z: [[f64; usize]; usize],
    x?: [f64; usize],
    y?: [f64; usize],
    name?: String,
    opacity?: f64,
    hover_template?: String,
    hover_template_array?: [String; usize],
    hover_text?: String,
    hover_text_array?: [String; usize],
    hover_text_matrix?: [[String; usize]; usize],
    text?: String,
    text_array?: [String; usize],
    text_matrix?: [[String; usize]; usize],
    show_legend?: bool,
    legend_group?: String,
    x_axis?: String,
    y_axis?: String,
    connect_gaps?: bool,
    transpose?: bool,
    auto_color_scale?: bool,
    reverse_scale?: bool,
    show_scale?: bool,
    zauto?: bool,
    zmax?: f64,
    zmin?: f64,
    zmid?: f64,
    x_gap?: usize,
    y_gap?: usize,
    hover_info?: "all" | "x" | "y" | "z" | "x+y" | "x+z" | "y+z" | "x+y+z" | "text" | "name" | "none" | "skip",
    color_bar?: ColorBar,
    color_scale?: "greys" | "ylgnbu" | "greens" | "ylorrd" | "bluered" | "rdbu" | "reds" | "blues" | "picnic" | "rainbow" | "portland" | "jet" | "hot" | "blackbody" | "earth" | "electric" | "viridis" | "cividis",
}

Data-mesh3d

mesh3d can be a Data entry. This Data will be rendered as a 3D mesh plot.

{
    type: "mesh3d",
    x: [f64; usize],
    y: [f64; usize],
    z: [f64; usize],
    i?: [usize; usize],
    j?: [usize; usize],
    k?: [usize; usize],
    name?: String,
    opacity?: f64,
    ids?: [String; usize],
    text?: String,
    text_array?: [String; usize],
    hover_text?: String,
    hover_text_array?: [String; usize],
    hover_template?: String,
    hover_template_array?: [String; usize],
    show_legend?: bool,
    legend_group?: String,
    legend_rank?: usize,
    color?: Color,
    face_color?: [Color; usize],
    vertex_color?: [Color; usize],
    intensity?: [f64; usize],
    intensity_mode?: "vertex" | "cell",
    scene?: String,
    flat_shading?: bool,
    alpha_hull?: f64,
    delaunay_axis?: "x" | "y" | "z",
    meta?: String,
    color_axis?: String,
    hover_info?: "all" | "x" | "y" | "z" | "x+y" | "x+z" | "y+z" | "x+y+z" | "text" | "name" | "none" | "skip",
    color_bar?: ColorBar,
    color_scale?: "greys" | "ylgnbu" | "greens" | "ylorrd" | "bluered" | "rdbu" | "reds" | "blues" | "picnic" | "rainbow" | "portland" | "jet" | "hot" | "blackbody" | "earth" | "electric" | "viridis" | "cividis",
    lighting?: { ambient?: f64, diffuse?: f64, specular?: f64, roughness?: f64, fresnel?: f64 },
    light_position?: { x?: f64, y?: f64, z?: f64 },
}

Data-scatter3d

scatter3d can be a Data entry. This Data will be rendered as a 3D scatter plot.

{
    type: "scatter3d",
    x: [f64; usize],
    y: [f64; usize],
    z: [f64; usize],
    name?: String,
    opacity?: f64,
    ids?: [String; usize],
    text?: String,
    text_array?: [String; usize],
    text_template?: String,
    text_template_array?: [String; usize],
    hover_text?: String,
    hover_text_array?: [String; usize],
    hover_template?: String,
    hover_template_array?: [String; usize],
    show_legend?: bool,
    legend_group?: String,
    legend_rank?: usize,
    surface_color?: Color,
    connect_gaps?: bool,
    scene?: String,
    meta?: String,
    mode?: "lines" | "markers" | "text" | "linesmarkers" | "linestext" | "markerstext" | "linemarkerstext" | "none",
    hover_info?: "all" | "x" | "y" | "z" | "x+y" | "x+z" | "y+z" | "x+y+z" | "text" | "name" | "none" | "skip",
    text_position?: "top left" | "top center" | "top right" | "middle left" | "middle center" | "middle right" | "bottom left" | "bottom center" | "bottom right",
    surface_axis?: "-1" | "0" | "1" | "2",
    marker?: Marker,
    line?: Line,
}

Data-surface

surface can be a Data entry. This Data will be rendered as a 3D surface plot.

{
    type: "surface",
    z: [[f64; usize]; usize],
    x?: [f64; usize],
    y?: [f64; usize],
    name?: String,
    opacity?: f64,
    text?: String,
    text_array?: [String; usize],
    hover_text?: String,
    hover_text_array?: [String; usize],
    hover_template?: String,
    hover_template_array?: [String; usize],
    show_legend?: bool,
    legend_group?: String,
    connect_gaps?: bool,
    hide_surface?: bool,
    surface_color?: [Color; usize],
    auto_color_scale?: bool,
    reverse_scale?: bool,
    show_scale?: bool,
    cauto?: bool,
    cmax?: f64,
    cmin?: f64,
    cmid?: f64,
    hover_info?: "all" | "x" | "y" | "z" | "x+y" | "x+z" | "y+z" | "x+y+z" | "text" | "name" | "none" | "skip",
    color_bar?: ColorBar,
    color_scale?: "greys" | "ylgnbu" | "greens" | "ylorrd" | "bluered" | "rdbu" | "reds" | "blues" | "picnic" | "rainbow" | "portland" | "jet" | "hot" | "blackbody" | "earth" | "electric" | "viridis" | "cividis",
    lighting?: { ambient?: f64, diffuse?: f64, specular?: f64, roughness?: f64, fresnel?: f64 },
    light_position?: { x?: i32, y?: i32, z?: i32 },
}

Sand Box Script

Warning

This format is deprecated. Using it will emit a warning and a debug message, and fall back to rendering the default chart.

This format allows you to define a script that runs in a local sandboxed environment. Upon execution, the script generates the corresponding chart object.

Output Formats

Output formats determine whether the final rendered result is HTML, SVG, or another format. Each format has its own advantages and trade-offs—we leave the choice to the user.

Output format must be configured globally; for details, see Configuration.

Raw Name	Formatted Name	Effect	Additional Notes
PlotlyHtml	`plotly-html`	Outputs an `<div>` element and a companion `<script>` containing Plotly logic	May cause compatibility issues with Markdown parsers that do not support raw HTML; less suitable for client-side rendering scenarios
PlotlySvg	`plotly-svg`	TODO	Not yet implemented; intended to perform most rendering locally, but may increase build time

FilesExpand file tree

USAGE.md

Latest commit

History

USAGE.md

File metadata and controls

mdbook-plotly User Manual

Table of Contents

Quick Start

Installation

Using Cargo

Manual Download

Basic Configuration

First Chart Example

TUI Edition

Installing the Full Edition

The tui Command

Schema Language

GitHub Proxy / Mirror

Configuration Reference

Configuration Syntax

Configuration Options

map-eval configuration

map-parser-extensions feature

Input Formats

JSON Input

JSON Syntax and Type System

Basic Types

Common Composite Types

Common Complex Types

Map and Generators

Generator Types

Generator Types

Using the Map

Chart Main Format

Layout Format

Axis Reference

Dual Y-Axis Example

Config Format

Data-bar

Data-candlestick

Data-density_mapbox

Data-histogram

Data-ohlc

Data-image

Data-pie

Data-sankey

Data-scatter_geo

Data-scatter_mapbox

Data-scatter_polar

Data-scatter

Data-table

Data-box

Data-contour

Data-heatmap

Data-mesh3d

Data-scatter3d

Data-surface

Sand Box Script

Output Formats

The `tui` Command

`map-eval` configuration

`map-parser-extensions` feature