gem-hunter

A plotly.js React component from Plotly.

• Installation
• Quick start
• State management
• Refreshing the Plot
• API
  • Basic props
  • Event handler props
• Examples
  • Responsive plot
  • Event handlers
  • TypeScript
  • Grabbing the graph div via ref
• Customizing the plotly.js bundle
• Loading from a <script> tag
• Development

$ npm install react-plotly.js plotly.js

The easiest way to use this component is to import and pass data to a plot component:

import Plot from 'react-plotly.js';

function App() {
  return (
    <Plot
      data={[
        {
          x: [1, 2, 3],
          y: [2, 6, 3],
          type: 'scatter',
          mode: 'lines+markers',
          marker: {color: 'red'},
        },
        {type: 'bar', x: [1, 2, 3], y: [2, 5, 3]},
      ]}
      layout={{width: 320, height: 240, title: {text: 'A Fancy Plot'}}}
    />
  );
}

You should see a plot like this:

For a full description of Plotly chart types and attributes see the following resources:

• Plotly JavaScript API documentation
• Full plotly.js attribute listing

This is a "dumb" component that doesn't merge its internal state with any updates. This means that if a user interacts with the plot, by zooming or panning for example, any subsequent re-renders will lose this information unless it is captured and upstreamed via the onUpdate callback prop.

Here is a simple example of how to capture and store state in a parent object:

import {useState} from 'react';
import Plot from 'react-plotly.js';

function App() {
  const [figure, setFigure] = useState({data: [], layout: {}, frames: [], config: {}});
  return (
    <Plot
      data={figure.data}
      layout={figure.layout}
      frames={figure.frames}
      config={figure.config}
      onInitialized={setFigure}
      onUpdate={setFigure}
    />
  );
}

This component will refresh the plot via Plotly.react if any of the following are true:

• The revision prop is defined and has changed, OR;
• One of data, layout or config has changed identity as checked via a shallow ===, OR;
• The number of elements in frames has changed

Furthermore, when called, Plotly.react will only refresh the data being plotted if the identity of the data arrays (e.g. x, y, marker.color etc) has changed, or if layout.datarevision has changed.

In short, this means that simply adding data points to a trace in data or changing a value in layout will not cause a plot to update unless this is done immutably via something like immutability-helper if performance considerations permit it, or unless revision and/or layout.datarevision are used to force a rerender.

Warning: for the time being, this component may mutate its layout and data props in response to user input, going against React rules. This behaviour will change in the near future once plotly/plotly.js#2389 is completed.

Refs: a ref attached to <Plot> resolves to the rendered <div> element (the plotly graph div), so you can call low-level plotly.js APIs against it directly (e.g. Plotly.toImage(ref.current)).

TypeScript: this package ships its own declaration files. Trace and layout shapes are typed as unknown since the wrapper does not bind to a specific plotly.js type surface; consumers wanting tighter typing on the data / layout props can re-declare them locally.

Note: To make a plot responsive, i.e. to fill its containing element and resize when the window is resized, use style or className to set the dimensions of the element (i.e. using width: 100%; height: 100% or some similar values) and set useResizeHandler to true while setting layout.autosize to true and leaving layout.height and layout.width undefined. A short example is in the Responsive plot section below. See also the responsive layout reference.

The onInitialized, onUpdate and onPurge props are all functions which will be called with two arguments: figure and graphDiv.

• figure is a serializable object with three keys corresponding to input props: data, layout and frames.
  • As mentioned above, for the time being, this component may mutate its layout and data props in response to user input, going against React rules. This behaviour will change in the near future once plotly/plotly.js#2389 is completed.
• graphDiv is a reference to the (unserializable) DOM node into which the figure was rendered.

Event handlers for specific plotly.js events may be attached through the following props:

To receive onClick or onHover for positions that are not over a trace, set clickanywhere or hoveranywhere in your layout. These are layout attributes rather than distinct events: the ordinary plotly_click / plotly_hover fire with an empty points array, plus xvals / yvals — arrays of the cursor position in data space, one entry per axis.

<Plot
  data={data}
  layout={{clickanywhere: true}}
  onClick={(e) => console.log(e.points, e.xvals, e.yvals)}
/>

To make the plot fill its container and resize with the window, leave the layout's width/height unset, enable autosize, and turn on useResizeHandler. Size the wrapper <div> with style or className:

<Plot
  data={[{x: [1, 2, 3], y: [2, 6, 3], type: 'scatter'}]}
  layout={{autosize: true, title: {text: 'Responsive'}}}
  style={{width: '100%', height: '100%'}}
  useResizeHandler
/>

All plotly.js events are surfaced as on<EventName> props (see the Event handler props table). Each handler receives the raw plotly.js event payload:

<Plot
  data={[{x: [1, 2, 3], y: [2, 6, 3], type: 'scatter', mode: 'markers'}]}
  layout={{title: {text: 'Click me'}}}
  onClick={(event) => {
    const point = event.points[0];
    console.log(`clicked (${point.x}, ${point.y})`);
  }}
  onRelayout={(event) => {
    if (event['xaxis.range[0]']) {
      console.log('user zoomed to', event['xaxis.range[0]'], event['xaxis.range[1]']);
    }
  }}
/>

The package ships its own declaration files.

import Plot, {PlotParams, Figure} from 'react-plotly.js';

const onUpdate = (figure: Figure, gd: HTMLElement) => {
  console.log('figure data length:', figure.data.length, 'gd id:', gd.id);
};

const params: PlotParams = {
  data: [{x: [1, 2, 3], y: [2, 6, 3], type: 'scatter'}],
  layout: {title: {text: 'Typed'}},
  onUpdate,
};

export const App = () => <Plot {...params} />;

A ref attached to <Plot> resolves to the rendered plotly graph div. Use it to call low-level plotly.js APIs:

import {useRef} from 'react';
import Plot from 'react-plotly.js';
import Plotly from 'plotly.js';

function ExportButton() {
  const ref = useRef(null);
  const exportPng = async () => {
    const dataUrl = await Plotly.toImage(ref.current, {format: 'png'});
    console.log(dataUrl);
  };
  return (
    <>
      <Plot ref={ref} data={[{x: [1, 2, 3], y: [2, 6, 3], type: 'scatter'}]} layout={{}} />
      <button onClick={exportPng}>Export PNG</button>
    </>
  );
}

By default, the Plot component exported by this library loads a precompiled version of all of plotly.js, so plotly.js must be installed as a peer dependency. This bundle is around 6Mb unminified, and minifies to just over 2Mb.

If you do not wish to use this version of plotly.js, e.g. if you want to use a different precompiled bundle or if your wish to assemble you own customized bundle, or if you wish to load plotly.js from a CDN, you can skip the installation of as a peer dependency (and ignore the resulting warning) and use the createPlotComponent method to get a Plot component, instead of importing it:

// simplest method: uses precompiled complete bundle from `plotly.js`
import Plot from 'react-plotly.js';

// customizable method: use your own `Plotly` object
import createPlotlyComponent from 'react-plotly.js/factory';
const Plot = createPlotlyComponent(Plotly);

For quick one-off demos in JSFiddle or similar environments, you can load the component directly as a script tag. We don't host the bundle ourselves, so don't rely on this in production, but you can pull it from a CDN such as unpkg or jsdelivr:

<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://cdn.plot.ly/plotly-3.6.0.min.js"></script>
<script src="https://unpkg.com/react-plotly.js@latest/dist/create-plotly-component.min.js"></script>

React is pinned to 18 here because React 19 stopped shipping UMD builds; consumers wanting React 19 should load it via importmap or use a bundler.

The factory is exposed as the global createPlotlyComponent. Build the component and mount it:

const Plot = createPlotlyComponent(Plotly);
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  React.createElement(Plot, {
    data: [{x: [1, 2, 3], y: [2, 1, 3]}],
  })
);

To get started:

$ npm install

To build the published artifacts (dist/index.{mjs,cjs}, dist/factory.{mjs,cjs}, the UMD bundle, and the declaration files) via tsup:

$ npm run build

To run lint + typecheck + jest:

$ npm run test

To watch source files and rebuild on change:

$ npm run watch

Releases are cut from main per the steps in RELEASE.md.

© 2017-2026 Plotly, Inc. MIT License.