<widget-linechart>

A Lit 3.x web component for rendering interactive line, bar, and scatter charts using ECharts. Part of the IronFlock widget ecosystem.

Installation

npm i @record-evolution/widget-linechart

Usage

Bundled Application (Vite/Webpack)

When using a bundler, install the widget and its peer dependencies:

npm i @record-evolution/widget-linechart echarts@^6.0.0 tinycolor2@^1.6.0

Then import and use:

<script type="module">
    import '@record-evolution/widget-linechart/widget-linechart.js'
</script>

<widget-linechart-1.6.28></widget-linechart-1.6.28>

The bundler will automatically deduplicate echarts across multiple widgets.

CDN / Import Maps

For CDN usage without a bundler, configure an import map with all dependencies:

<script>
    // Polyfill for Node.js process.env required by echarts
    window.process = { env: { NODE_ENV: 'production' } }
</script>

<script type="importmap">
    {
        "imports": {
            "echarts/core": "https://cdn.jsdelivr.net/npm/[email protected]/core.js",
            "echarts/charts": "https://cdn.jsdelivr.net/npm/[email protected]/charts.js",
            "echarts/components": "https://cdn.jsdelivr.net/npm/[email protected]/components.js",
            "echarts/renderers": "https://cdn.jsdelivr.net/npm/[email protected]/renderers.js",
            "echarts/features": "https://cdn.jsdelivr.net/npm/[email protected]/features.js",
            "zrender/": "https://cdn.jsdelivr.net/npm/[email protected]/",
            "tslib": "https://cdn.jsdelivr.net/npm/[email protected]/tslib.es6.mjs",
            "tinycolor2": "https://cdn.jsdelivr.net/npm/[email protected]/+esm"
        }
    }
</script>

<script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@record-evolution/[email protected]/dist/widget-linechart.js"
></script>

<widget-linechart-1.6.28></widget-linechart-1.6.28>

Note: Version matching is critical - echarts 6.0.0 requires zrender 6.0.0 exactly.

Dependencies

This widget has been optimized to externalize heavy dependencies:

• echarts (^6.0.0) - Chart rendering engine (~300KB)
• tinycolor2 (^1.6.0) - Color manipulation utilities

Bundle size: ~36KB (down from 625KB with bundled echarts)

Configuration

The widget accepts an inputData property with the following structure:

Axis Configuration (axis)

| Option | Type | Default | Description | | -------------- | ------- | ------- | --------------------------------------------------------- | | showLegend | boolean | true | Display the chart legend | | showTitle | boolean | true | Display the chart title | | showBox | boolean | false | Display a border frame around the chart area | | timeseries | boolean | false | Enable time series x-axis (x-values should be timestamps) | | columnLayout | boolean | false | Stack multiple charts vertically instead of horizontally | | xAxisLabel | string | - | Label for the x-axis | | showXAxis | boolean | true | Show/hide x-axis and labels | | xAxisZoom | boolean | false | Enable zoom tool on x-axis | | yAxisLabel | string | - | Label for the y-axis (positioned at top) | | showYAxis | boolean | true | Show/hide y-axis and labels | | yAxisScaling | boolean | false | Scale y-axis to data range (otherwise starts at 0) |

Data Series (dataseries[])

| Option | Type | Description | | --------------------- | ---------------------------------- | ------------------------------------------------------------- | | label | string | Series name shown in legend | | type | "line" | "bar" | "scatter" | Chart type for this series | | data | array | Array of { x, y, r?, pivot? } data points | | backgroundColor | color | Fill color for area/bars | | borderColor | color | Line/border color | | styling.borderWidth | number | Line width (default: 2) | | styling.borderDash | string | Line style: "solid", "dashed", "dotted" | | styling.fill | boolean | Fill area under line | | styling.pointStyle | string | Point shape: "circle", "rect", "triangle", "none" | | advanced.chartName | string | Group series into named charts; use #split# for auto-naming | | advanced.drawOrder | number | Z-index for layering series |

Expected Data Format

See src/default-data.json for a complete example.

Features

• Chart types: line, bar, scatter (via dataseries[].type)
• Time series: Set axis.timeseries: true for date-based x-axis
• Multi-chart: Use advanced.chartName to split series into separate charts
• Pivot/Split: data[].pivot auto-generates series per distinct value
• Adaptive animation: Animation duration automatically matches data update frequency
• Dynamic theming: Supports ECharts theme objects via the theme property
• Visibility controls: Toggle legend, title, axes, and box frame independently
• Y-axis label: Positioned at top of axis to avoid overlap with tick labels

Performance Optimizations

• Efficient data-only updates using setOption() merge mode
• Full rebuild only on configuration changes (detected via config fingerprinting)
• ResizeObserver-based chart resizing (no polling)
• Adaptive animation timing based on actual update intervals

Local Demo

npm start

Runs a development server at http://localhost:8000/demo/