@richpods/echarts-sandbox

A secure Web Component for rendering ECharts charts inside a sandboxed iframe. This isolates potentially untrusted chart configurations from your application, preventing XSS attacks through ECharts' HTML-rendering features in tooltips and other parts.

Why this package?

ECharts has known security concerns when processing untrusted configurations:

• tooltip.formatter accepts raw HTML
• URL properties can contain javascript: protocols
• Various HTML/CSS injection points

This package renders charts inside an iframe with sandbox="allow-scripts" only—no access to your page's DOM, cookies, or local storage.

Installation

npm install @richpods/echarts-sandbox

Usage

Via HTML attribute (JSON string)

<script type="module">
    import "@richpods/echarts-sandbox";
</script>

<echarts-sandbox
    config='{"xAxis":{},"yAxis":{},"series":[{"type":"bar","data":[1,2,3,4,5]}]}'
></echarts-sandbox>

Via JavaScript property

<echarts-sandbox id="chart"></echarts-sandbox>

<script type="module">
    import "@richpods/echarts-sandbox";

    const chart = document.getElementById("chart");
    chart.config = {
        xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
        yAxis: { type: "value" },
        series: [{ type: "bar", data: [120, 200, 150, 80, 70] }],
    };
</script>

Updating the chart

// Merge new options (like ECharts setOption)
chart.setOption({
    series: [{ data: [100, 150, 200, 250, 300] }],
});

// Replace entire config
chart.config = newConfig;

// Clear the chart
chart.clear();

API

Attributes

| Attribute | Type | Description | | ------------- | ----------- | ----------------------------------------------- | | config | JSON string | Chart configuration | | echarts-src | string | Custom ECharts script URL (default: CDN v6.0.0) | | theme | string | ECharts theme name |

Properties

| Property | Type | Description | | -------- | ------ | --------------------------- | | config | object | Get/set chart configuration |

Methods

| Method | Description | | -------------------------- | ------------------------------------------ | | setOption(option, opts?) | Update chart options (mirrors ECharts API) | | clear() | Clear the chart |

Events

| Event | Detail | Description | | ----------------- | --------------------- | -------------------------- | | ready | {} | Chart initialized | | error | { message: string } | Error occurred | | chart-click | ECharts params | Chart click | | chart-mouseover | ECharts params | Mouse over chart element | | chart-mouseout | ECharts params | Mouse out of chart element |

All ECharts events are forwarded with a chart- prefix.

chart.addEventListener("chart-click", (e) => {
    console.log("Clicked:", e.detail.params);
});

Custom ECharts CDN Source

By default, ECharts is loaded from esm.sh CDN. To use a different version or your own hosted copy:

<echarts-sandbox echarts-src="https://your-cdn.com/echarts.min.js" config="..."></echarts-sandbox>

Styling

You must specify a height and width to render an ECharts graphics. The component fills its container. Set dimensions on the element or its parent:

echarts-sandbox {
    width: 100%;
    height: 400px;
}

License

ISC