Use this skill when working with Plotly.js in JavaScript/TypeScript frontend projects. Covers debugging Plotly code, implementing specific chart types (candlestick, 3D surfaces, choropleth maps), React integration with react-plotly.js, and version migration between v1/v2/v3. Trigger when users mention Plotly.js explicitly, show Plotly code with errors, or need Plotly-specific features like financial charts or 3D visualizations. Do not trigger for Python/Jupyter notebooks, R data science, or general charting library recommendation questions without Plotly context.
package.json or CDN script tagsreact-plotly.js — if not present, recommend installing it rather than doing manual DOM manipulationAlways run this first when starting work with Plotly.js:
# Check npm dependency
grep -E "\"plotly.js|\"react-plotly" package.json
# Also check for CDN usage in HTML files
grep -r "cdn.plot.ly/plotly\|plotly-latest\|plotly\.js" --include="*.html" .
Extract the major version number:
const plotlyVersion = pkg.dependencies?.['plotly.js'] ||
pkg.devDependencies?.['plotly.js'] ||
pkg.dependencies?.['plotly.js-dist'] ||
pkg.dependencies?.['plotly.js-dist-min'];
const major = parseInt(plotlyVersion?.match(/\d+/)?.[0] ?? '');
Also check for partial bundles — Plotly ships several:
plotly.js — full bundle (~3.5 MB minified)plotly.js-dist / plotly.js-dist-min — pre-bundled full distributionplotly.js-basic-dist — basic charts only (scatter, bar, pie)plotly.js-cartesian-dist — cartesian chartsplotly.js-geo-dist — geographic chartsplotly.js-gl3d-dist — WebGL 3D chartsplotly.js-gl2d-dist — WebGL 2D charts (removed in v3)plotly.js-mapbox-dist — mapbox charts (deprecated in v3)plotly.js-finance-dist — financial chartsThe partial bundle determines which chart types are available. If the user tries to use a chart type not in their bundle, suggest either switching to the full bundle or the appropriate partial bundle.
Before suggesting Plotly.js patterns, scan for existing charting libraries:
grep -E "\"chart\.js\"|\"recharts\"|\"victory\"|\"highcharts\"|\"apexcharts\"|\"echarts\"|\"@nivo\"|\"visx\"|\"d3\"" package.json
If a competing library is found, ask the user before proceeding. Plotly can coexist with other libraries, but mixing chart libraries in the same project adds bundle size and inconsistency.
Exception: d3 as a dependency does not count as a competing chart library — Plotly.js itself uses D3 internally. Only flag D3 if the user is using it directly for charting (check for d3.select patterns creating SVG charts).
title: "My Chart" — this is the original formataggregate, filter, groupby, sort)$(graphDiv).on('plotly_click', ...) workspointcloud and heatmapgl availablescattermapbox, choroplethmapbox, densitymapbox supportKey changes from v1:
title: { text: "My Chart" } is now the canonical form. Plain strings still work but are deprecatedmapbox traces deprecated (v2.35+): New map traces introduced (scattermap, choroplethmap, densitymap) using MapLibre instead of Mapbox GL JS — no access token neededsubtitle added (v2.34+): layout.title.subtitle for chart subtitleslegend2, legend3, etc. in layoutzorder (v2.31+): Control stacking order of cartesian tracesmarker.cornerradius for rounded barsinsiderange (v2.27+): Avoid tick label overlap on inner axeslabel attribute on shapes with texttemplatelegend.xref/yref = "container"@types/plotly.js (community maintained)// v2 title (canonical form)
Plotly.newPlot('div', data, {
title: { text: 'Revenue by Quarter', font: { size: 20 } }
});
// v2.35+ map traces (replaces mapbox)
{
type: 'scattermap',
lat: [45.5, 46.0],
lon: [-73.5, -74.0],
mode: 'markers'
}
Major breaking changes from v2:
// v1-v2: Plain string works