ECharts Family

Installation

echarts is an optional peer dependency: install it in the host application and the family lights up, leave it out and nothing else in Tuffex changes. It is never bundled — the components import it dynamically, so it lands in its own chunk the first time one of them mounts.

pnpm add echarts @talex-touch/tuffex

import { TxEChart, TxLineChart } from '@talex-touch/tuffex/charts'

Usage

Best Practices

• Give the host a definite height. A zero-height container cannot paint.
• Prefer a typed wrapper. For a sunburst, pass hierarchical data with type: 'sunburst' directly to TxEChart; its runtime registers that series. For other long-tail types, obtain the runtime through loadECharts() and register the corresponding ECharts module first.
• Use aria-label: the label makes a canvas chart readable to assistive tech.
• Pass data, not pixels: the wrappers map your data onto the option, so theme colours and axis chrome stay consistent.
• Install echarts in the host application; a missing peer is reported in the container instead of failing silently.

API Reference

Every chart in the family accepts the shared props below plus its own data props, and every one forwards a raw option that is merged over the built option — series arrays are replaced, every other key merges deep.

update only exists on TxEChart: 'replace' (default) swaps the series array so removed series stop being drawn, 'merge' keeps ECharts' own merge semantics.

Per-chart props

The builders themselves are public too — buildBarChartOption, buildLineChartOption, and the rest return a plain EChartsOption. Use one when a chart has to mix mark types: build the options you want and hand the merged result to TxEChart.

Themed host

TxEChart owns the lifecycle: it resolves the chart tokens for the current theme, applies them, then paints your option over them. Sunburst is registered and accepts hierarchical data directly; other ECharts types not registered by the host require their corresponding modules first.

<script setup lang="ts">
import { TxEChart } from '@talex-touch/tuffex/charts'
import type { EChartsOption } from 'echarts'

const option: EChartsOption = {
  tooltip: { trigger: 'item' },
  series: [{
    type: 'sunburst',
    radius: ['20%', '90%'],
    data: [
      { name: '2.5.x', children: [{ name: '2.5.1-beta.2', value: 40 }, { name: '2.5.0', value: 35 }] },
      { name: '2.4.x', children: [{ name: '2.4.13', value: 25 }] },
    ],
  }],
}
</script>

<template>
  <TxEChart :option="option" :height="280" aria-label="Version families and exact versions" />
</template>

Charts

Line chart

TxLineChart draws one or more series over a category axis, with optional area fill, stacking and smooth curves. Multiple series share the axis; the tooltip triggers by axis so every series at the hovered category is listed.

Bar chart

TxBarChart draws grouped or stacked bars on a category axis, vertical by default. stacked gives every series that declares no stack of its own the shared id total, so stacked and independent series can share one chart; showLabel writes the value on each bar (to its right when horizontal).

Pie chart

Slices of one whole, optionally hollow. donut takes true for a 60% hole or a number for an exact inner-radius percent; centerLabel renders inside a donut only, and labelPosition moves the slice labels outside, inside or into the centre.

Funnel chart

Stage-by-stage conversion. sort reorders the stages (descending by default) and labelPosition: 'outside' maps onto ECharts' outer position, so stage names sit beside the funnel instead of inside it. Each label's share is measured against the first element of data, so pass the stages in the order you want them counted.

Radar chart

Several entities measured on one set of axes. Every entry of indicators becomes a spoke, and each series supplies values positionally, so data[i] belongs to indicators[i]. shape switches the frame between polygon and circle, splitNumber sets the number of rings, and showAxisName: false drops the spoke labels when the surrounding copy already names them.

Gauge chart

One reading on a dial — or a thin ring when progress is set. precision controls the decimals in the reading and unit is appended with no separator, so 72 with % renders as 72%. color tints the progress ring and the reading, never the dial, so the axis chrome stays themed.

Scatter chart

Points on a numeric plane, one axis pair per series. symbolSize sets the mark size for the whole chart and a series-level value wins; the optional xMin / xMax / yMin / yMax pin the domain when several charts have to share one scale.

Heatmap chart

A matrix of intensities. Pass values row-major (values[row][column]) with rows and columns naming the two category axes. The builder hands both arrays to ECharts untouched, and ECharts plots the first category at the bottom — so rows[0] is the bottom band, not the top one. The declared visualMap takes the sequential token ramp unless you pass your own inRange.color.

Treemap chart

Part-to-whole for a hierarchy. Nodes nest through children, a node's color becomes its fill, and showBreadcrumb turns on ECharts' breadcrumb bar for drilling down. maxDepth renders only the first N levels and enables that drill-down; leave it out to draw the whole tree. Without children the same prop draws a flat treemap.

Events

Technologies

• Component source: packages/tuffex/packages/components/src/charts/src/echart/src/.
• Option builders: packages/tuffex/packages/components/src/charts/src/echart/src/options/.
• Theme and tokens: packages/tuffex/packages/components/src/charts/src/echart/src/core/theme.ts.
• Adapted from Cloudflare kumo (https://github.com/cloudflare/kumo), © Cloudflare, Inc., MIT — EChart.tsx.

Use cases

The native SVG family (TxChart, TxTimeseriesChart, TxSankeyChart, TxChoroplethMap, TxSparkChart, TxAllocationBar) stays the default: smaller, themeable through CSS tokens, and shaped for what the product actually renders. Reach for TxEChart and its typed wrappers when you need a chart type the native family does not have, or when you want ECharts' own option surface — dataZoom, visualMap, custom series, per-point styling.

Both families read the same colour tokens, so an ECharts chart dropped next to a native one matches it in either theme without a single styling prop.