Getting started

Why EmKit

What a chart library leaves to you, and what these components do instead.

The samples assume the ChartsProvider from step 2 of the quick start.

A chart library such as Chart.js or Recharts draws the chart. A dashboard also needs formatting, consistent colours, gap-free time series, loading and error states, export and translations around it. That work is the same in every product.

EmKit is that work, done once, behind one API: describe your fields, pass your rows. The same card written both ways is below.

What you would otherwise build

What a dashboard needsWith a chart libraryWith EmKit
Number, currency and date formattingWrite formatters for ticks, tooltips and labels, per chart and per localePer field: prefix, suffix, decimals, currency, compact numbers, in the reader’s locale
One colour per value across the dashboardKeep your own colour map and pass it to every chartAutomatic, shared by every chart, kept across refreshes; pin any value
Missing time periodsLines join straight across gaps unless you fill them yourselfFilled per granularity and time zone, including ISO weeks and quarters
Changing granularityBuild a picker and re-bucket the dataPicker in the card header; you re-query at the chosen granularity
Comparison periodsWork out the previous range and overlay a second seriesComparison lines and KPI deltas from a second result set
Loading, empty and error statesDesign and wire three states for every chartDesigned states in every card, driven by the same results prop
Card, title and info tooltipBuild the card around the canvasEvery chart is a finished card
CSV, Excel and PNG exportWrite the export codeIn every card’s menu, with a maximize view
TranslationsThread i18n through titles, axes, legends and tooltipsTitles, field names and values translate; English, German and French built in
Click eventsMap canvas hit-tests back to your rowsTyped payloads with the clicked value and its time range
Tables, pivots and heat mapsA separate table library with its own data shape and stylingSame field descriptions, same response shape, same theme
Charts chosen by an AI modelDesign a schema, validate the model’s output, map it to chartsA tool definition and a renderer that repairs common model mistakes

The same card, written twice

One revenue card with loading, empty and error states, formatted values and an export, as two complete files. On a chart library it is 97 lines before the CSS, with one export format, one language and no click handler. On EmKit it is 29, and that file is running on the home page.

RevenueByRegionChartJs.tsx
import { useMemo } from 'react';
import { Bar } from 'react-chartjs-2';
import {
  BarElement,
  CategoryScale,
  Chart,
  Legend,
  LinearScale,
  Tooltip,
} from 'chart.js';

Chart.register(BarElement, CategoryScale, Legend, LinearScale, Tooltip);

type Row = { region: string; revenue: number };

type Props = {
  rows?: Row[];
  isLoading: boolean;
  error?: string;
};

const money = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: 'USD',
  maximumFractionDigits: 0,
});

const downloadCsv = (rows: Row[]) => {
  const lines = rows.map((row) => `"${row.region}",${row.revenue}`);
  const csv = ['Region,Revenue', ...lines].join('\n');
  const link = document.createElement('a');
  link.href = URL.createObjectURL(new Blob([csv], { type: 'text/csv' }));
  link.download = 'revenue-by-region.csv';
  link.click();
};

export function RevenueByRegion({ rows, isLoading, error }: Props) {
  const data = useMemo(
    () => ({
      labels: (rows ?? []).map((row) => row.region),
      datasets: [
        {
          label: 'Revenue',
          data: (rows ?? []).map((row) => row.revenue),
        },
      ],
    }),
    [rows],
  );

  let body = (
    <div className="card__chart">
      <Bar
        data={data}
        options={{
          responsive: true,
          maintainAspectRatio: false,
          plugins: {
            tooltip: {
              callbacks: {
                label: (item) => money.format(Number(item.parsed.y)),
              },
            },
          },
          scales: {
            y: {
              ticks: { callback: (value) => money.format(Number(value)) },
            },
          },
        }}
      />
    </div>
  );
  if (isLoading && !rows) {
    body = <div className="card__skeleton" aria-busy="true" />;
  } else if (error) {
    body = <p className="card__message" role="alert">{error}</p>;
  } else if (!rows?.length) {
    body = <p className="card__message">No results</p>;
  }

  return (
    <section className="card">
      <header className="card__header">
        <h3>Revenue by region</h3>
        <button
          type="button"
          disabled={!rows?.length}
          onClick={() => downloadCsv(rows ?? [])}
        >
          Download CSV
        </button>
      </header>
      {body}
    </section>
  );
}
RevenueByRegion.tsx
import { BarChart, dimension, measure } from 'em-kit';
import type { BarChartOptionsClickArg } from 'em-kit';

type Props = {
  rows?: { region: string; revenue: number }[];
  isLoading: boolean;
  error?: string;
  onBarClicked?: (bar: BarChartOptionsClickArg) => void;
};

const region = dimension({ name: 'region', title: 'Region' });
const revenue = measure({
  name: 'revenue',
  title: 'Revenue',
  inputs: { prefix: '$' },
});

export function RevenueByRegion(props: Props) {
  const { rows, isLoading, error, onBarClicked } = props;
  return (
    <BarChart
      title="Revenue by region"
      dimension={region}
      measures={[revenue]}
      results={{ isLoading, error, data: rows }}
      onBarClicked={onBarClicked}
    />
  );
}

Across a whole app the difference in lines is smaller, because fetching, filters and layout are yours either way. What stays different is that every card is finished, and finished the same way.

What stays yours

  • Your data layer. EmKit never fetches. Pass rows from any API, warehouse or cache.
  • Every display option. Each one is an optional prop that overrides a default.
  • The look. Design tokens for colour, type and spacing, and Chart.js options per chart type. See Theming.
  • Custom charts. When no component fits, build one from the same toolkit. See Build your own chart.

What it adds to your bundle

About 256 KB of JavaScript, minified and gzipped, with React left out: Chart.js and its plugins are about 86 KB of that. Importing every component costs about 4 KB more than importing one. Spreadsheet and image export (about 167 KB) load only when a reader chooses them from a chart’s menu.

When it pays off

The saving grows with the number of cards. One chart on one page is quick to build on a chart library, by hand or with a coding assistant. EmKit earns its place when:

  • You have many cards. Ten charts and tables that must load, fail, format and export alike. Each new card is a few lines, and none of them needs states or formatting of its own.
  • Customers see them. Empty and error states, keyboard access to every control, readable axes and phone layouts are done and tested. A hand-built card gets them one bug report at a time.
  • You theme or translate. One theme restyles every card, dark mode included. One locale changes every number and date, and the built-in text comes in English, German and French.
  • You need tables and export too. Paginated and pivot tables, heat maps and KPIs take the same fields as the charts, and every card exports CSV, Excel and PNG.
  • A coding assistant writes the code. It writes less, and you review less: the states, formatting and export are the library’s, already tested, not new code in every pull request.

When to use something else

  • One or two simple charts. A chart library is lighter: EmKit adds about 256 KB however few components you use.
  • A visualisation no dashboard chart covers, such as a custom D3 graphic or a map. Use a lower-level library; the build toolkit can still give it the same card, formatting and colours.
  • Control of every pixel. The components take options, tokens and Chart.js settings, not replacement parts.
  • An app that is not React. The components need React 19.

If you need the data layer too

EmKit is Embeddable’s chart components as a standalone React library: you bring the data. Inside Embeddable the same components are called Remarkable Pro.

Embeddable adds the data layer, multi-tenant security and self-serve dashboards for your customers.