Guide · Open source

How to use plotly.js: load it, draw a chart and customise it

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Plotly.js is an open-source JavaScript library that draws interactive charts in a web page, including statistical, 3D, scientific, map and financial charts. You describe your data and layout as a JSON-like object, and the library renders the chart. This guide is for web developers and analysts who want to add interactive charts to a site or app, and it covers installing the library, drawing a first chart and the main options you will need.

Plotly.jsplotly/plotly.js · ★ 18.4k · MIT Install options & downloads

Quick start

1Confirm Node.js is available. Node.js is the stated prerequisite for the npm install. If you only use a script tag, you can skip the npm step.
2Install the distributed bundle. Run npm i --save plotly.js-dist-min in your project folder to add the minified bundle.
3Import or require the library. Use an ES6 import or a CommonJS require to load plotly.js-dist-min in your code.
4Create a div to hold the chart. Add an HTML element with an id, such as gd, where the chart will be drawn.
5Call Plotly.newPlot. Pass the div id, a data array of series and a layout object with options such as width and height.
6Adjust the chart. Change the data and layout objects to set size, labels and chart type.

What plotly.js is and who it suits

Plotly.js is a standalone JavaScript data visualization library. The same library also powers the Python and R packages named plotly, so charts built in those ecosystems rely on the JavaScript code underneath.

You only need basic HTML and JSON syntax to get started. The library is a good fit when you want interactive charts without writing much code, or when you need chart types such as 3D graphs or scientific charts for a dashboard.

Web developers adding interactive charts to their own site or app
Data analysts who already use Plotly in Python or R and want to understand the JavaScript side
Teams building dashboards that need 3D or scientific chart types

Load plotly.js with npm or a script tag

For a project that uses Node.js, install the ready-to-use distributed bundle with npm. You can then import it as an ES6 module or load it with require in Node.js. The README also mentions plotly.js-dist as an option if you prefer an unminified package.

If you are not using a build step, add a script tag that points to a CDN file. The README notes that the CDN files are versioned, so you must name an exact plotly.js version when using the CDN with v2 and higher.

Prerequisite: Node.js, needed for the npm install
Use plotly.js-dist-min for the minified bundle or plotly.js-dist for the unminified one
Fastly provides a free CDN for plotly.js, according to the README

npm i --save plotly.js-dist-min

Draw your first chart with Plotly.newPlot

The Plotly object is added to the window scope by the script tag. Call newPlot with the id of an HTML div, then pass a JSON object with a data array and a layout object. The data array holds the series, and the layout sets things like width and height.

The example below draws a single series in a div with the id gd. The layout sets the width to 600 and the height to 400.

Create a div with an id, such as gd, to hold the chart
Put the series in the data array, for example { "y": [1, 2, 3] }
Set size and other options in the layout object

<head>
    <script src="https://cdn.plot.ly/plotly-4.2.0.min.js" charset="utf-8"></script>
</head>
<body>
    <div id="gd"></div>

    <script>
        Plotly.newPlot("gd", /* JSON object */ {
            "data": [{ "y": [1, 2, 3] }],
            "layout": { "width": 600, "height": 400}
        })
    </script>
</body>

Use native ES6 modules in the browser

You can also load the library with a native ES6 import inside a script tag of type module. The README shows the same newPlot call used after the import, with the data written as a plain array.

Set the script tag type to module
Import the library URL, then call Plotly.newPlot on your div

<script type="module">
    import "https://cdn.plot.ly/plotly-4.2.0.min.js"
    Plotly.newPlot("gd", [{ y: [1, 2, 3] }])
</script>

Add LaTeX math with MathJax (optional)

Plotly.js can render mathematical expressions using MathJax v3 or v4. MathJax is not included in the bundle, so you must load it as a separate script on the page. When MathJax is available, any text between dollar signs is rendered with MathJax, including plot titles, axis labels, tick labels and annotations.

The README says the svg renderer used by plotly.js does not stop other MathJax renderers from working elsewhere on the page.

MathJax v4 and v3 are both supported, and the README gives a script URL for each
Wrap expressions in $ signs to render them

<script src="https://cdn.jsdelivr.net/npm/mathjax@4.1.3/tex-svg.js"></script>

Choose a bundle or build a custom one

The official bundles are complete or partial builds published to npm and the CDN. The README warns that the full build is large, so if bundle size matters you can create a custom bundle with only the parts you need, following the CUSTOM_BUNDLE guide in the repository.

If you need to bundle lib/index.js directly or change the default build configuration, the README points to BUILDING.md.

Complete and partial official bundles are described in the dist README
Custom bundles let you reduce size by including only what you need
Several WebGL graphs on one page: the README suggests the virtual-webgl script for WebGL 1, not WebGL 2

What people use it for

Adding interactive charts to a company website or web app
Building dashboards that include 3D or scientific chart types
Drawing map and financial charts inside a browser page
Showing equations on chart titles and axes with MathJax

Frequently asked questions

Is plotly.js free to use?

Yes. Plotly.js is released under the MIT licence, as shown in the README. Check the LICENSE file in the repository for the full terms.

What do I need to install plotly.js?

The README lists Node.js as the prerequisite for the npm install. You can also load the library through a script tag from a CDN without installing anything.

How do I install plotly.js with npm?

Run npm i --save plotly.js-dist-min. The README recommends this ready-to-use distributed bundle for npm projects.

Why is my plotly.js bundle so large?

The README says the full build is large. To reduce size, create a custom bundle or use a partial bundle that includes only the modules you need.

Can I use plotly.js with several WebGL charts on one page?

The README suggests loading the virtual-webgl script for WebGL 1 before other scripts. It does not describe WebGL 2 support, so do not assume WebGL 2 features will work.

What are the alternatives to plotly.js?

The comparable projects listed for this directory are Chart.js, Apache ECharts, D3.js and Vega-Lite. A lighter library such as Chart.js may suit simple charts better.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Plotly.js suits web developers and analysts who want interactive charts, including 3D and scientific types, and who are comfortable with basic HTML and JSON. Pick a lighter library if you only need a simple static chart or if strict bundle size limits apply and you are not ready to build a custom bundle.

Install options & downloads