Repository files navigation

Aplotly.js React component fromPlotly. The basis of Plotly'sReact component suite.

👉DEMO

👉Demo source code

• Installation
• Quick start
• State management
• Refreshing the Plot
• API
  • Basic props
  • Event handler props
• Customizing theplotly.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:

importReactfrom'react';importPlotfrom'react-plotly.js';classAppextendsReact.Component{render(){return(<Plotdata={[{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:'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 theonUpdate callback prop.

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

classAppextendsReact.Component{constructor(props){super(props);this.state={data:[],layout:{},frames:[],config:{}};}render(){return(<Plotdata={this.state.data}layout={this.state.layout}frames={this.state.frames}config={this.state.config}onInitialized={(figure)=>this.setState(figure)}onUpdate={(figure)=>this.setState(figure)}/>);}}

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

• Therevision prop is defined and has changed, OR;
• One ofdata,layout orconfig has changed identity as checked via a shallow===, OR;
• The number of elements inframes has changed

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

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

Warning: for the time being, this component maymutate itslayout anddata props in response to user input, going against React rules. This behaviour will change in the near future onceplotly/plotly.js#2389 is completed.

Note: To make a plot responsive, i.e. to fill its containing element and resize when the window is resized, usestyle orclassName to set the dimensions of the element (i.e. usingwidth: 100%; height: 100% or some similar values) and setuseResizeHandler totrue while settinglayout.autosize totrue and leavinglayout.height andlayout.width undefined. This can be seen in action inthis CodePen and will implement the behaviour documented here:https://plot.ly/javascript/responsive-fluid-layout/

TheonInitialized,onUpdate andonPurge props are all functions which will be called with two arguments:figure andgraphDiv.

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

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

By default, thePlot component exported by this library loads a precompiled version of all ofplotly.js, soplotly.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 ofplotly.js, e.g. if you want to use adifferent precompiled bundle or if your wish toassemble you own customized bundle, or if you wish to loadplotly.jsfrom a CDN, you can skip the installation of as a peer dependency (and ignore the resulting warning) and use thecreatePlotComponent method to get aPlot component, instead of importing it:

// simplest method: uses precompiled complete bundle from `plotly.js`importPlotfrom'react-plotly.js';// customizable method: use your own `Plotly` objectimportcreatePlotlyComponentfrom'react-plotly.js/factory';constPlot=createPlotlyComponent(Plotly);

For quick one-off demos onCodePen orJSFiddle, you may wish to just load the component directly as a script tag. We don't host the bundle directly, so you should never rely on this to work forever or in production, but you can use a third-party service to load the factory version of the component from, for example,https://unpkg.com/react-plotly.js@latest/dist/create-plotly-component.js.

You can load plotly.js and the component factory with:

<scriptsrc="https://cdn.plot.ly/plotly-latest.min.js"></script><scriptsrc="https://unpkg.com/react-plotly.js@latest/dist/create-plotly-component.js"></script>

And instantiate the component with

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

You can see an example of this method in actionhere.

To get started:

$ npm install

To transpile from ES2015 + JSX into the ES5 npm-distributed version:

$ npm run prepublishOnly

To run the tests:

$ npm runtest

© 2017-2020 Plotly, Inc. MIT License.