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.

---

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)

---

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)