Chart

Chart renders Matplotlib, Plotly, Altair, or raw SVG and HTML outputs in a single component.

Quick Start

Live Preview

from faststrap import Chart

Chart(fig, backend="matplotlib")

Plotly and Altair

Chart(fig, backend="plotly", include_js=True)

If your figure object exposes to_html(), Chart can render it directly.

For Plotly, include_js=True asks Plotly to include its JavaScript from a CDN. If your layout already loads Plotly globally, leave include_js=False.

Raw SVG or HTML

Raw strings require explicit opt-in for safety:

Chart("<svg>...</svg>", backend="svg", allow_unsafe_html=True)

Backend Inference

If you pass a Matplotlib or Plotly/Altair object, Chart will infer the backend automatically. Raw strings always require backend to be specified.

Sizing and Responsiveness

responsive=True adds w-100 to the wrapper.
Use width and height for fixed sizing.

Chart(fig, backend="matplotlib", width=480, height=320)

Parameters

Parameter	Type	Default	Description
`figure`	`Any`	required	Matplotlib figure, Plotly/Altair chart, or trusted raw string.
`backend`	`matplotlib \\| plotly \\| altair \\| svg \\| html \\| None`	`None`	Explicit renderer. Required for raw strings.
`include_js`	`bool`	`False`	Include Plotly JavaScript when rendering Plotly charts.
`responsive`	`bool`	`True`	Adds `w-100` to the wrapper.
`width`	`str \\| int \\| None`	`None`	Wrapper width. Integers become pixel values.
`height`	`str \\| int \\| None`	`None`	Wrapper height. Integers become pixel values.
`allow_unsafe_html`	`bool`	`False`	Required for raw SVG/HTML strings.
`**kwargs`	`Any`		Extra wrapper attributes.

Theming

Chart does not auto-theme plots. Use your chart library to set colors for dark mode and match your theme palette.

Security Notes

If you render raw SVG or HTML, only use trusted content. Set allow_unsafe_html=True only when you control the source.

API Reference

`faststrap.components.display.chart.Chart(figure, *, backend=None, include_js=False, responsive=True, width=None, height=None, allow_unsafe_html=False, **kwargs)`

Render a chart from common Python plotting backends.

Parameters:

Name	Type	Description	Default
`figure`	`Any`	Matplotlib figure, Plotly/Altair chart, or raw SVG/HTML string.	required
`backend`	`ChartBackend \| None`	Explicit backend name. If None, attempts to infer from object.	`None`
`include_js`	`bool`	Include Plotly JS when rendering Plotly charts.	`False`
`responsive`	`bool`	Apply responsive sizing classes.	`True`
`width`	`str \| int \| None`	Optional width (px or CSS string).	`None`
`height`	`str \| int \| None`	Optional height (px or CSS string).	`None`
`allow_unsafe_html`	`bool`	Allow raw HTML/SVG strings to be embedded.	`False`
`**kwargs`	`Any`	Additional HTML attributes for the wrapper.	`{}`

Source code in src/faststrap/components/display/chart.py

@register(category="display")
@beta
def Chart(
    figure: Any,
    *,
    backend: ChartBackend | None = None,
    include_js: bool = False,
    responsive: bool = True,
    width: str | int | None = None,
    height: str | int | None = None,
    allow_unsafe_html: bool = False,
    **kwargs: Any,
) -> Div:
    """Render a chart from common Python plotting backends.

    Args:
        figure: Matplotlib figure, Plotly/Altair chart, or raw SVG/HTML string.
        backend: Explicit backend name. If None, attempts to infer from object.
        include_js: Include Plotly JS when rendering Plotly charts.
        responsive: Apply responsive sizing classes.
        width: Optional width (px or CSS string).
        height: Optional height (px or CSS string).
        allow_unsafe_html: Allow raw HTML/SVG strings to be embedded.
        **kwargs: Additional HTML attributes for the wrapper.
    """
    cfg = resolve_defaults(
        "Chart",
        responsive=responsive,
        include_js=include_js,
        allow_unsafe_html=allow_unsafe_html,
    )
    c_responsive = cfg.get("responsive", responsive)
    c_include_js = cfg.get("include_js", include_js)
    c_allow_unsafe_html = cfg.get("allow_unsafe_html", allow_unsafe_html)

    content: str

    if backend is None:
        if hasattr(figure, "savefig"):
            backend = "matplotlib"
        elif hasattr(figure, "to_html"):
            backend = "plotly"
        elif isinstance(figure, str):
            msg = "Chart backend must be specified when passing a raw string."
            raise ValueError(msg)
        else:
            msg = "Unable to infer chart backend. Please pass backend explicitly."
            raise TypeError(msg)

    if backend == "matplotlib":
        content = _matplotlib_to_svg(figure)
    elif backend in {"plotly", "altair"}:
        content = _to_html(figure, include_js=c_include_js)
    elif backend in {"svg", "html"}:
        if not isinstance(figure, str):
            msg = f"Chart backend '{backend}' expects a string input."
            raise TypeError(msg)
        if not c_allow_unsafe_html:
            msg = "allow_unsafe_html=True is required to embed raw HTML/SVG strings."
            raise ValueError(msg)
        content = figure
    else:
        msg = f"Unsupported chart backend: {backend}"
        raise ValueError(msg)

    classes = ["faststrap-chart"]
    if c_responsive:
        classes.append("w-100")

    user_cls = kwargs.pop("cls", "")
    wrapper_cls = merge_classes(" ".join(classes), user_cls)

    style: dict[str, Any] = {}
    normalized_width = _normalize_size(width)
    normalized_height = _normalize_size(height)
    if normalized_width:
        style["width"] = normalized_width
    if normalized_height:
        style["height"] = normalized_height

    attrs: dict[str, Any] = {"cls": wrapper_cls}
    if style:
        attrs["style"] = style
    attrs.update(convert_attrs(kwargs))

    return Div(NotStr(content), **attrs)