Plotly.js

3.5.0 · active · verified Sun Apr 19

Plotly.js is an open-source JavaScript data visualization library that provides a wide array of interactive, publication-quality charts and graphs. It is the core engine powering the popular Plotly.py and Plotly.R libraries, offering a unified graphing experience across different programming environments. The library supports dozens of chart types, including statistical, 3D, scientific, SVG/tile maps, and financial charts. It is currently stable at version 3.5.0, with minor releases featuring new attributes, bug fixes, and performance improvements appearing frequently. Its key differentiators include comprehensive chart type support, robust interactivity features, and its foundational role in the broader Plotly ecosystem, enabling complex data narratives in web applications. It can be used as a Node.js module via bundled distributions or directly in the browser via script tags and CDNs.

Warnings

breaking Plotly.js v3.0.0 introduced significant breaking changes, including dropping support for string values in the `title` attribute, and removing deprecated attributes like `titlefont`, `titleposition`, `titleside`, `titleoffset` (now under `title.font`, `title.side`, `title.offset`). It also removed traces `pointcloud` and `heatmapgl`, and attributes such as `bardir` (use `orientation`), `annotation.ref` (use `annotation.xref`/`yref`), and error bar `opacity` (use alpha channel of `color`). Support for jQuery events was also removed.
Fix: Consult the Plotly.js v3 migration guide for detailed attribute mapping and update chart configurations accordingly. Ensure all title-related attributes are nested under `title.*` and use modern attribute equivalents.
breaking Plotly.js v3.x now requires Node.js version 18.0.0 or higher. Deployments or development environments running older Node.js versions will encounter errors.
Fix: Upgrade Node.js to version 18.0.0 or newer.
gotcha When importing Plotly.js as a module, it is crucial to use the specific distributed bundles like `plotly.js-dist-min` (minified) or `plotly.js-dist` (unminified) rather than the bare `plotly.js` package name. Direct import from `plotly.js` can lead to incorrect bundling or larger artifact sizes.
Fix: Always use `import Plotly from 'plotly.js-dist-min'` or `require('plotly.js-dist-min')` for module usage.
gotcha The `Plotly` object is a default export when used as an ES module or CommonJS module. Attempting to use named imports (e.g., `import { Plotly } from 'plotly.js-dist-min'`) will result in an undefined `Plotly` object or an error, as no such named export exists.
Fix: Always use default import syntax: `import Plotly from 'plotly.js-dist-min'` or `const Plotly = require('plotly.js-dist-min')`.
breaking A regression introduced in Plotly.js 3.0.0 affected the editable `title.text` property for `ternary`, `polar`, `colorbar`, and `rangeslider` components. Users upgrading to versions `>=3.0.0` but `<3.1.2` might experience issues with these editable titles.
Fix: Ensure your Plotly.js version is 3.1.2 or newer to resolve this specific regression.

Install

npm install plotly.js npm
yarn add plotly.js yarn
pnpm add plotly.js pnpm

Imports

Plotly
wrong:
```
import { Plotly } from 'plotly.js-dist-min'
```
correct:
```
import Plotly from 'plotly.js-dist-min'
```
For ES modules, `Plotly` is the default export. Use `plotly.js-dist-min` for a minified production bundle or `plotly.js-dist` for an unminified version.
Plotly
wrong:
```
const { Plotly } = require('plotly.js-dist-min')
```
correct:
```
const Plotly = require('plotly.js-dist-min')
```
For CommonJS environments, `Plotly` is the module's export. Similar to ESM, use the bundled packages (`plotly.js-dist-min` or `plotly.js-dist`).
Plotly
wrong:
```
<script type="module"> import { Plotly } from "https://cdn.plot.ly/plotly-3.5.0.min.js" </script>
```
correct:
```
<script src="https://cdn.plot.ly/plotly-3.5.0.min.js"></script>
```
When loaded via a traditional script tag or an ES module script tag, the `Plotly` object becomes available globally on the `window` object. Direct named imports from the CDN URL are not supported for this global bundle.

Quickstart

This example demonstrates how to embed a simple interactive scatter plot using Plotly.js directly in an HTML file via CDN, initializing it with basic data and layout configurations.

<!DOCTYPE html>
<html>
<head>
    <title>Plotly.js Quickstart</title>
    <script src="https://cdn.plot.ly/plotly-3.5.0.min.js" charset="utf-8"></script>
</head>
<body>
    <h1>Simple Plotly.js Chart</h1>
    <div id="myDiv" style="width:600px;height:400px;"></div>

    <script type="text/javascript">
        // Data for the plot
        const trace1 = {
            x: [1, 2, 3, 4],
            y: [10, 15, 13, 17],
            mode: 'markers',
            type: 'scatter',
            name: 'Trace 1'
        };

        const trace2 = {
            x: [1, 2, 3, 4],
            y: [16, 5, 11, 9],
            mode: 'lines+markers',
            type: 'scatter',
            name: 'Trace 2'
        };

        const data = [trace1, trace2];

        // Layout for the plot
        const layout = {
            title: 'My First Plotly.js Graph',
            xaxis: { title: 'X-axis Label' },
            yaxis: { title: 'Y-axis Label' }
        };

        // Create the plot in the div with id 'myDiv'
        Plotly.newPlot('myDiv', data, layout);

        console.log("Plotly chart rendered successfully!");
    </script>
</body>
</html>

view raw JSON →