Skip to main content

@britecharts/react

@britecharts/react is a package that allows you use [Britecharts][britecharts] within React applications.

Usage​

Every chart in @britecharts/react is a function component: you pass in some props, and it renders a chart.

import { Bar } from '@britecharts/react';

const data = [
    {
        name: 'Vibrant',
        value: 2,
    },
    {
        name: 'Opalescent',
        value: 4,
    },
    {
        name: 'Shining',
        value: 3,
    },
];

<Bar
    data={data}
    width={400}
    isHorizontal
/>

Check our Storybook for more examples and check the source to copy/paste code.

Loading data​

data is required. Pass null while it loads: nothing is drawn until it arrives, and the chart is drawn as soon as it does. Leaving data out, or passing undefined, is an error (and a type error, too).

<Bar data={isLoading ? null : data} />

Updating a chart​

A chart is redrawn when its props change, and only then. On every render the data and each configuration value are compared with what was last drawn, so a re-render with the same props costs nothing. The consequence is that the data has to be a new array or object to be redrawn: mutating it in place and re-rendering with the same reference does nothing.

setData([...data, newPoint]); // redraws
data.push(newPoint);
setData(data); // does not: same array, nothing changed

No instance, no ref​

Function components have no instance to point a ref at, so a ref on a chart is not accepted (the typings say so). A chart is drawn into a <div> the component owns, and removes what it drew when it unmounts.

Tooltips​

A Tooltip wraps the chart it decorates: give it a render prop that returns the chart, and pass on the props it hands you, which are what connect the two.

import { Line, Tooltip } from '@britecharts/react';

<Tooltip
    data={data}
    render={(props) => <Line {...props} />}
    topicLabel="topics"
    title="A title"
/>

Responsive charts​

ResponsiveContainer hands its render prop the width it has measured, and measures again when the window is resized. withResponsiveness does the same for a component you wrap, as its width prop (a width you pass yourself wins).

import { Line, ResponsiveContainer, withResponsiveness } from '@britecharts/react';

<ResponsiveContainer
    render={({ width }) => <Line data={data} width={width} />}
/>

const ResponsiveLine = withResponsiveness(Line);

<ResponsiveLine data={data} />

API​

Each component's API is a reflection of [Britecharts][britecharts] charts and their APIs. They also have a bunch of React specific props, and there are some changes due to the declarative way of building with React.

For example, if we need to check the options of a bar chart, you will first check the bar chart's API in the main project API reference page.

The complete set of components is in progress; the following components are currently implemented and available for use:

  • Bar charts (API)
  • Bullet charts (API)
  • Grouped Bar charts (API)
  • Donut charts (API)
  • Line charts (API)
  • Scatter Plots (API)
  • Sparkline charts (API)
  • Stacked Area charts (API)
  • Stacked Bar charts (API)
  • Tooltips (API), wrapping the line, stacked area, stacked bar and grouped bar charts with a list of values, and the bar, scatter plot and heatmap charts with a single value (the mini tooltip)
  • Legends (API)
  • The ResponsiveContainer component and the withResponsiveness function, described above

The following components haven't been adapted yet from Britecharts:

  • Brush charts
  • Heatmaps

These components were previously hosted in the britecharts-react repository, but became a package with Britecharts V3.

Installation​

To install run:

yarn add @britecharts/core @britecharts/wrappers @britecharts/react

Or, with npm:

npm i --save @britecharts/core @britecharts/wrappers @britecharts/react

Britecharts-React is available as an NPM module or through CDN links (in different formats or a bundle).

Each component is also published on its own, in UMD format (dist/umd/charts/<Component>.js) and CommonJS format (dist/cjs/charts/<Component>.js); in both the module is the component, so require('@britecharts/react/dist/cjs/charts/Donut.js') returns Donut. The React consumer in the integration package shows every way of loading it, and is what CI runs.

Supported React versions​

peerDependencies requires react and react-dom >=16.8: the components use hooks, which arrived in that release. What is actually verified on every commit:

  • React 19, by the unit tests, which now run on React Testing Library, and in a real browser: CI packs the package the way a release does, installs it into a React 19 project, and loads it in production and in a development build under StrictMode, which runs every effect's setup, cleanup and setup again.

React 17 and 18 are expected to work and are not exercised. If you hit a version-specific problem on an older React, please open an issue.

Acknowledgments​

For this project, we have followed the approach called ‘Mapping Lifecycle methods’ based on Nicholas Hery's article: a chart's create, update and destroy are called from the component's mount, update and unmount, which one internal hook now does for every chart. We want to recognize all the contributors in the parent project [Britecharts][britecharts].

See Also​

Contribute​

If you need to use one of the missing charts, check out our how-to guide for creating new charts. Check also the contributing guide if you want to help us bringing these in.

Note that the aim of this project is to allow the usage of Britecharts within your React applications. For that, we are ‘wrapping’ Britecharts with @britecharts/wrappers. This means that any new features need to first be implemented on Britecharts. Only then you could update the props and logic that passes in the configuration.

Roadmap​

The typings are hand-written .d.ts declarations, checked in CI by a TypeScript project that consumes the packed package. Our idea for the short term is to write the package in TypeScript natively. For that, we already have an initial version in TS-wip/ that we need to polish and reproduce. Let us know if you want to help with it.