jervis-charts

jervis-charts/native is a dependency-free, native-SVG chart Web Component. It is the recommended starting point when you want responsive charts without adding a charting library. The package also provides isolated adapters for Highcharts, Chart.js, ApexCharts, Apache ECharts, uPlot, D3, and the native renderer.

Install and start with native SVG

npm install jervis-charts

import { defineJervisChart } from 'jervis-charts/native';

defineJervisChart();

const chart = document.querySelector('jervis-chart');
chart.config = responseItem;
chart.appearance = {
  height: 360,
  colors: ['#2563eb', '#14b8a6', '#0ea5e9'],
  legend: 'auto',
  legendPosition: 'bottom',
  grid: true,
  tooltip: true
};

The native adapter supports bar, column, line, spline, area, and pie, renders SVG, and needs no third-party chart package.

Choose an engine

Import exactly one engine entry in applications that do not use the Vite plugin. Install the matching optional peer dependency for every non-native entry you use.

| Engine | Import | Install | | --- | --- | --- | | Native SVG | jervis-charts/native | npm install jervis-charts | | Highcharts | jervis-charts/highcharts | npm install jervis-charts highcharts | | Chart.js | jervis-charts/chartjs | npm install jervis-charts chart.js | | ApexCharts | jervis-charts/apexcharts | npm install jervis-charts apexcharts | | Apache ECharts | jervis-charts/echarts | npm install jervis-charts echarts | | uPlot | jervis-charts/uplot | npm install jervis-charts uplot | | D3 | jervis-charts/d3 | npm install jervis-charts d3 |

import { defineJervisChart } from 'jervis-charts/chartjs';

defineJervisChart();

Highcharts licensing is the consumer's responsibility. All entries define the same custom element API; only the selected adapter is bundled by a normal ESM build.

Vite: recommended explicit selection

Use the Vite plugin with an explicit engine when the application has one known chart engine. It rewrites the root jervis-charts import to the selected engine entry, so the build contains one engine.

// vite.config.js
import { defineConfig } from 'vite';
import { jervisCharts } from 'jervis-charts/vite';

export default defineConfig({
  plugins: [jervisCharts({ engine: 'native' })]
});

// app.js
import { defineJervisChart } from 'jervis-charts';

defineJervisChart();

The plugin can instead infer an engine from a static tag attribute:

<jervis-chart engine="chartjs"></jervis-chart>

Static inference scans HTML, Vue, JSX, and TSX sources. It is deterministic: every discovered static tag must select the same engine, or the build fails. Use one engine per build to preserve tree-shaking.

If engine is set at runtime, make the provider build-time-known with configFile:

jervisCharts({ configFile: './src/modules/statistics/config.js' })

The configured file must contain chartControls: { provider: 'chartjs' } (or another supported engine). Changing that file while Vite is running requires restarting Vite. For explicit configuration shared by the app and Vite, keep the provider in a small imported module and pass it as engine.

Data contract

The response item retains the existing Highcharts-shaped contract:

interface JervisChartItem<TOptions extends object = object> {
  key: string;
  title: string;
  type: 'bar' | 'column' | 'line' | 'spline' | 'area' | 'pie';
  size?: { cols?: string; md?: string; lg?: string };
  data: Partial<Record<ChartType, TOptions>>;
}

Use JervisChartItem<Highcharts.Options> when the response is typed with Highcharts; no string index signature is required.

Adapters translate categories, series, colors, and pie points for the six chart types. Highcharts receives native options; other engine-specific options may produce development warnings. uPlot renders line, spline, and area natively; its categorical bar, column, and pie support uses the adapter's lightweight canvas fallback.

D3 supports begin-at-zero domains, all legend positions, data labels, and HTML tooltips, but warns in development when explicit animation is requested. uPlot preserves null gaps, maps tooltips to its live cursor legend, positions the static series legend, and supports data labels in the categorical canvas fallback. uPlot line/area data labels and animation are unsupported and produce development warnings when explicitly requested; the categorical canvas fallback does not provide per-point hover tooltips.

Component API

Set object values as JavaScript properties, not serialized HTML attributes.

chart.loading = false;
chart.error = null;
chart.appearance = {
  height: 420,
  fontFamily: 'Cairo, sans-serif',
  fontSize: 13,
  axisLabelGap: 12,
  yAxisLabelGap: 10,
  lineWidth: 3,
  showPoints: 'auto',
  pointRadius: 4,
  barRadius: 8,
  barThickness: 42,
  donutSize: 60,
  dataLabels: false
};

// Advanced native options: applied after the shared options where supported.
chart.providerOptions = {
  options: { interaction: { mode: 'nearest' } }
};

appearance controls card styling, typography, palette, axes and grid, legend and tooltip, animation, lines and points, bars, donut size, data labels, title, and toolbar. providerOptions is merged last by Highcharts, Chart.js, ApexCharts, ECharts, and uPlot. D3 uses appearance only because it has no native options object.

Properties are engine, config, loading, error, selectedType, showPng, showSvg, showFullscreen, appearance, providerOptions, messages, and ariaLabel. messages can localize loading, empty, error, chartType, downloadPng, downloadSvg, and fullscreen. Call exportChart('png' | 'svg') to trigger an available export. The component emits jervis-type-change, jervis-export, and jervis-error.

Customize accessible control and status text with messages, and label the chart with ariaLabel or aria-label:

chart.messages = {
  loading: 'Loading revenue',
  empty: 'No revenue data',
  chartType: 'Display as',
  downloadPng: 'Download chart as PNG',
  downloadSvg: 'Download chart as SVG',
  fullscreen: 'Open fullscreen'
};
chart.ariaLabel = 'Quarterly revenue by region';

For custom empty content, add an empty slot. Replace the type selector with a type-selector slot; buttons with data-chart-type and selects with data-chart-type-selector are wired automatically. Active custom buttons receive data-active and aria-pressed="true"; unavailable types are hidden.

<jervis-chart id="chart" dir="rtl" aria-label="مبيعات أسبوعية حسب القناة">
  <div slot="type-selector">
    <button type="button" data-chart-type="column">Columns</button>
    <button type="button" data-chart-type="line">Line</button>
  </div>
  <div slot="empty">No results for this filter.</div>
</jervis-chart>

Set dir="rtl" on the element or inherit the page direction. Toolbar actions are independently configurable with showPng, showSvg, and showFullscreen, or their show-png, show-svg, and show-fullscreen attributes. SVG export appears only when the adapter supports it; Chart.js exposes PNG export. Fullscreen uses the browser Fullscreen API.

CSS variables include --jervis-chart-height, --jervis-chart-bg, --jervis-chart-text, --jervis-chart-muted, --jervis-chart-border, --jervis-chart-radius, and --jervis-chart-font. Style the built-in selector with jervis-chart::part(type-selector).

Frameworks

The Custom Element works with vanilla JavaScript, Vue, React, Angular, Svelte, and other frameworks that support custom elements. Assign config, appearance, and providerOptions as element properties.

Vue 3:

<script setup>
import { onMounted, ref } from 'vue';
import { defineJervisChart } from 'jervis-charts/native';

defineJervisChart();
const chart = ref();
onMounted(() => { chart.value.config = responseItem; });
</script>

<template><jervis-chart ref="chart" /></template>

React:

import { useEffect, useRef } from 'react';
import { defineJervisChart } from 'jervis-charts/native';

defineJervisChart();
export function Chart({ item }) {
  const chart = useRef(null);
  useEffect(() => { chart.current.config = item; }, [item]);
  return <jervis-chart ref={chart} />;
}

Compatibility

| Integration | Supported versions | | --- | --- | | Node.js | ^20.19.0 or >=22.12.0 | | ApexCharts | >=4 <7 | | Chart.js | >=4 <5 | | D3 | >=7 <8 | | Apache ECharts | >=5 <7 | | Highcharts | >=11 <14 | | uPlot | >=1 <2 |

Development and release verification

npm install
npm run check
npm run build:example
npm run release:check
npm run pack:check

Use npm run dev to serve the vanilla example. Do not open examples/vanilla/index.html with file://; package imports need a dev server or bundler.