Struct ChartContainerProps 

pub struct ChartContainerProps {

    pub series: Option<Vec<SeriesDef>>,
    pub dataset: Option<Dataset>,
    pub binding: Option<ChartFieldBinding>,
    pub x_axis: Option<Vec<AxisDef>>,
    pub y_axis: Option<Vec<AxisDef>>,
    pub width: Option<f64>,
    pub height: Option<f64>,
    pub margin: Option<PlotInset>,
    pub grid: Option<GridConfig>,
    pub loading: Option<bool>,
    pub skip_animation: Option<bool>,
    pub motion: Option<ChartMotion>,
    pub orientation: ChartOrientation,
    pub chart_kind: ChartKind,
    pub highlight_scope: Option<HighlightScope>,
    pub axis_highlight: Option<AxisHighlightConfig>,
    pub legend: Option<LegendConfig>,
    pub tooltip: Option<TooltipConfig>,
    pub charts_theme: Option<OrbitalChartsTheme>,
    pub palette: Option<OrbitalChartPalette>,
    pub highlighted_item: Option<RwSignal<Option<ChartItemId>>>,
    pub on_highlight_change: Option<Callback<(Option<ChartItemId>,), ()>>,
    pub on_legend_click: Option<Callback<(String,), ()>>,
    pub on_item_click: Option<Callback<(ChartItemId,), ()>>,
    pub on_axis_click: Option<Callback<(AxisClickData,), ()>>,
    pub features: ChartFeatures,
    pub keyboard_navigation: bool,
    pub prefer_line_x_strict: bool,
    pub zoom: Option<Vec<ZoomWindow>>,
    pub on_zoom_change: Option<Callback<(Vec<ZoomWindow>,), ()>>,
    pub loading_view: Option<Arc<dyn Fn() -> AnyView + Send + Sync>>,
    pub empty_view: Option<Arc<dyn Fn() -> AnyView + Send + Sync>>,
    pub embed_mode: ChartEmbedMode,
    pub overlay_mount: OverlayMount,
    pub class: MaybeProp<String>,
    pub children: Option<Children>,
}

Props for the ChartContainer component.

Ready-made chart layout root — bind a Dataset, tune props, or compose plot children.

Use ChartContainer when you need explicit control over axes, series, plot inset, and child plot layers. For common chart types, prefer the *Chart convenience components (e.g. crate::BarChart).

Chart type family

Pick the chart that matches the story you are telling:

• Compare categories — crate::BarChart when magnitude at a shared baseline matters.
• Show change over time — crate::LineChart or crate::AreaChart for trends and stacked volume.
• Show parts of a whole — crate::PieChart when proportions beat precise comparisons.
• Correlate two metrics — crate::ScatterChart for point-by-point relationships.
• Inline trend glyph — crate::Sparkline beside KPIs without axis chrome.
• Single-metric readout — crate::Gauge for capacity or score at a glance.
• Intensity grid — crate::Heatmap for two categorical dimensions plus a value.

Customization layers

1. Single *Chart component — bind a Dataset and optional legend / tooltip props.
2. Configuration props — axes, plot inset (margin), palette, highlight scope on the container.
3. Composition children — ChartContainer + explicit BarPlot / LinePlot / custom SVG layers. See chart-composition and chart-stacking previews.

Cross-cutting UX lives on dedicated previews: charts-legend, charts-tooltip, charts-highlighting, charts-label, charts-styling, charts-axis.

When to use

• Mixed-type dashboards (bar + line overlay) or custom SVG annotations.
• Full control over which plot children render and their z-order.
• Processed Dataset output from a DataTable without a convenience *Chart wrapper.

Usage

1. Bind a shared Dataset with binding or field keys that match your DataTable columns.
2. Set explicit width and height for fixed tiles, or wrap with ResponsiveChartContainer for parent-fill layouts.
3. Add plot children (BarPlot, LinePlot, etc.) in composition mode; otherwise the container renders axes only.
4. Opt into legend, tooltip, and highlight_scope when the dashboard needs exploration — defaults are None for lightweight embeds.
5. Wrap previews in a native element with data-testid for E2E hooks.

Best Practices

Do’s

• Use the same field keys as orbital_data::FieldDef::key in your DataTable columns.
• Leave skip_animation unset so reduced-motion preferences are honored automatically.
• Set plot inset via margin when legends or long axis labels need extra room.
• Link users to cross-cutting previews instead of repeating legend/tooltip setup on every chart type.
• Follow [ChartCompositionOrder] for child z-order: grid → [PlotClip] → plots → axes → overlay chrome.
• Set embed_mode=ChartEmbedMode::ScrollHost when the chart lives inside a ScrollArea so tooltips escape clip.

Don’ts

• Do not reach for composition when a *Chart wrapper already covers your chart type.
• Do not put data-testid on the chart component — wrap it in a native div or span.
• Do not rely on absolute tooltip positioning in scroll hosts — use ChartEmbedMode instead.

Examples

Basic container with axes and grid

Minimal shell proving band x-axis, linear y-axis, and grid wiring. Start here before adding plot children or binding a live Dataset from a DataTable.

use crate::ChartContainer;
use crate::preview::fixtures::{full_grid, quarter_x_axis, revenue_series, revenue_y_axis};
view! {
    <div data-testid="chart-container-preview" style="min-width: 560px; min-height: 320px;">
        <ChartContainer
            series=Some(vec![revenue_series()])
            x_axis=Some(vec![quarter_x_axis()])
            y_axis=Some(vec![revenue_y_axis()])
            grid=Some(full_grid())
            width=Some(520.0)
            height=Some(320.0)
        />
    </div>
}

Loading overlay

Sets loading=true while async data fetches run. The container shows [Spinner] and [Skeleton] chrome instead of an empty plot — pair with your data resource’s pending state.

use crate::ChartContainer;
view! {
    <div data-testid="chart-container-loading-preview">
        <ChartContainer loading=Some(true) width=Some(400.0) height=Some(280.0) />
    </div>
}

Custom layer via hooks

Dashed baseline drawn in SVG space using crate::use_drawing_area and crate::use_y_scale. Use this pattern for annotations that must stay aligned on resize.

use crate::{ChartContainer, ChartCustomBaseline};
use crate::preview::fixtures::{quarter_x_axis, revenue_series, revenue_y_axis};
view! {
    <div data-testid="chart-container-custom-layer-preview">
        <ChartContainer
            series=Some(vec![revenue_series()])
            x_axis=Some(vec![quarter_x_axis()])
            y_axis=Some(vec![revenue_y_axis()])
            width=Some(520.0)
            height=Some(320.0)
        >
            <ChartCustomBaseline />
        </ChartContainer>
    </div>
}

Optional Props

• series: Option<Vec<SeriesDef>>
  • Series definitions (explicit or derived from dataset + binding).
• dataset: Option<Dataset>
  • Tabular data — primary consumption mode.
• binding: Option<ChartFieldBinding>
  • Shorthand field binding when using dataset.
• x_axis: Option<Vec<AxisDef>>
  • X-axis definitions.
• y_axis: Option<Vec<AxisDef>>
  • Y-axis definitions.
• width: Option<f64>
  • Chart width in pixels.
• height: Option<f64>
  • Chart height in pixels.
• margin: Option<PlotInset>
  • Space between SVG border and plot. User docs: “plot inset”.
• grid: Option<GridConfig>
  • Background grid configuration.
• loading: Option<bool>
  • Whether the chart is in a loading state.
• skip_animation: Option<bool>
  • When true, skip all enter/update animations.
• motion: Option<ChartMotion>
  • Chart-level animation configuration.
• orientation: ChartOrientation
  • Chart orientation for cartesian plots.
• chart_kind: ChartKind
  • Chart geometry family.
• highlight_scope: Option<HighlightScope>
  • Highlight and fade scope.
• axis_highlight: Option<AxisHighlightConfig>
  • Axis crosshair / band highlight configuration.
• legend: Option<LegendConfig>
  • Legend configuration (None hides legend).
• tooltip: Option<TooltipConfig>
  • Tooltip configuration.
• charts_theme: Option<OrbitalChartsTheme>
  • Chart theme extension overrides.
• palette: Option<OrbitalChartPalette>
  • Color palette override.
• highlighted_item: Option<RwSignal<Option<ChartItemId>>>
  • Controlled highlighted item.
• on_highlight_change: Option<Callback<(Option<ChartItemId>,), ()>>
  • Fired when highlight changes.
• on_legend_click: Option<Callback<(String,), ()>>
  • Fired when a legend entry is clicked.
• on_item_click: Option<Callback<(ChartItemId,), ()>>
  • Fired when a bar/mark is clicked.
• on_axis_click: Option<Callback<(AxisClickData,), ()>>
  • Fired when a category axis band is clicked.
• features: ChartFeatures
  • Opt-in capability flags (ChartFeatures::ZOOM_PAN, ChartFeatures::ANIMATION, ChartFeatures::KEYBOARD_NAV).
• keyboard_navigation: bool
  • Enable arrow-key navigation between marks (CH-22). Keyboard zoom (CH-24) is deferred.
• prefer_line_x_strict: bool
  • When true, inferred line/area x-axes use crate::DomainLimit::Strict.
• zoom: Option<Vec<ZoomWindow>>
  • Controlled zoom windows per axis (percent 0–100).
• on_zoom_change: Option<Callback<(Vec<ZoomWindow>,), ()>>
  • Fired when the user or program changes zoom state.
• loading_view: [Option<Arc<dyn Fn() -> AnyView + Send + Sync>>]
  • Custom loading overlay slot.
• empty_view: [Option<Arc<dyn Fn() -> AnyView + Send + Sync>>]
  • Custom empty overlay slot.
• embed_mode: ChartEmbedMode
  • How the chart is embedded in its host (scroll, dialog, table cell).
• overlay_mount: OverlayMount
  • Portal mount override for overlay chrome.
• class: impl Into<MaybeProp<String>>
  • Optional CSS class on the root element.
• children: Children
  • Composition children (plot, axis, legend layers).

Fields

series: Option<Vec<SeriesDef>>

Series definitions (explicit or derived from dataset + binding).

dataset: Option<Dataset>

Tabular data — primary consumption mode.

binding: Option<ChartFieldBinding>

Shorthand field binding when using dataset.

x_axis: Option<Vec<AxisDef>>

X-axis definitions.

y_axis: Option<Vec<AxisDef>>

Y-axis definitions.

width: Option<f64>

Chart width in pixels.

height: Option<f64>

Chart height in pixels.

margin: Option<PlotInset>

Space between SVG border and plot. User docs: “plot inset”.

grid: Option<GridConfig>

Background grid configuration.

loading: Option<bool>

Whether the chart is in a loading state.

skip_animation: Option<bool>

When true, skip all enter/update animations.

motion: Option<ChartMotion>

Chart-level animation configuration.

orientation: ChartOrientation

Chart orientation for cartesian plots.

chart_kind: ChartKind

Chart geometry family.

highlight_scope: Option<HighlightScope>

Highlight and fade scope.

axis_highlight: Option<AxisHighlightConfig>

Axis crosshair / band highlight configuration.

legend: Option<LegendConfig>

Legend configuration (None hides legend).

tooltip: Option<TooltipConfig>

Tooltip configuration.

charts_theme: Option<OrbitalChartsTheme>

Chart theme extension overrides.

palette: Option<OrbitalChartPalette>

Color palette override.

highlighted_item: Option<RwSignal<Option<ChartItemId>>>

Controlled highlighted item.

on_highlight_change: Option<Callback<(Option<ChartItemId>,), ()>>

Fired when highlight changes.

on_legend_click: Option<Callback<(String,), ()>>

Fired when a legend entry is clicked.

on_item_click: Option<Callback<(ChartItemId,), ()>>

Fired when a bar/mark is clicked.

on_axis_click: Option<Callback<(AxisClickData,), ()>>

Fired when a category axis band is clicked.

features: ChartFeatures

Opt-in capability flags (ChartFeatures::ZOOM_PAN, ChartFeatures::ANIMATION, ChartFeatures::KEYBOARD_NAV).

keyboard_navigation: bool

Enable arrow-key navigation between marks (CH-22). Keyboard zoom (CH-24) is deferred.

prefer_line_x_strict: bool

When true, inferred line/area x-axes use crate::DomainLimit::Strict.

zoom: Option<Vec<ZoomWindow>>

Controlled zoom windows per axis (percent 0–100).

on_zoom_change: Option<Callback<(Vec<ZoomWindow>,), ()>>

Fired when the user or program changes zoom state.

loading_view: Option<Arc<dyn Fn() -> AnyView + Send + Sync>>

Custom loading overlay slot.

empty_view: Option<Arc<dyn Fn() -> AnyView + Send + Sync>>

Custom empty overlay slot.

embed_mode: ChartEmbedMode

How the chart is embedded in its host (scroll, dialog, table cell).

overlay_mount: OverlayMount

Portal mount override for overlay chrome.

class: MaybeProp<String>

Optional CSS class on the root element.

children: Option<Children>

Composition children (plot, axis, legend layers).

Implementations

impl ChartContainerProps

pub fn builder() -> ChartContainerPropsBuilder<((), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), ())>

Create a builder for building ChartContainerProps. On the builder, call .series(...)(optional), .dataset(...)(optional), .binding(...)(optional), .x_axis(...)(optional), .y_axis(...)(optional), .width(...)(optional), .height(...)(optional), .margin(...)(optional), .grid(...)(optional), .loading(...)(optional), .skip_animation(...)(optional), .motion(...)(optional), .orientation(...)(optional), .chart_kind(...)(optional), .highlight_scope(...)(optional), .axis_highlight(...)(optional), .legend(...)(optional), .tooltip(...)(optional), .charts_theme(...)(optional), .palette(...)(optional), .highlighted_item(...)(optional), .on_highlight_change(...)(optional), .on_legend_click(...)(optional), .on_item_click(...)(optional), .on_axis_click(...)(optional), .features(...)(optional), .keyboard_navigation(...)(optional), .prefer_line_x_strict(...)(optional), .zoom(...)(optional), .on_zoom_change(...)(optional), .loading_view(...)(optional), .empty_view(...)(optional), .embed_mode(...)(optional), .overlay_mount(...)(optional), .class(...)(optional), .children(...)(optional) to set the values of the fields. Finally, call .build() to create the instance of ChartContainerProps.

Trait Implementations

impl Props for ChartContainerProps

type Builder = ChartContainerPropsBuilder

fn builder() -> Self::Builder