Plotly.js for Svelte

This is an unofficial package that lets you efficiently use plotly.js inside your Svelte or SvelteKit app.

Usage

1. Install using pnpm add svelte-plotly.js or npm install svelte-plotly.js.
2. Choose a Plotly distribution:
- If you want to use plotly.js-dist, just install it.
- If you want to use a different distribution, take a look at this section.
3. Use in your app:

``svelte


{data}
layout={{
margin: { t: 0 }
}}
fillParent="width"
debounce={250}
/>
`

Custom Plotly distribution

Let's say you want to use svelte-plotly.js with a custom Plotly.js distribution, for example plotly.js-basic-dist-min. If you use Vite for bundling, the recommended way to do this would be to install plotly.js-basic-dist-min and then register it as an alias for plotly.js-dist by adding the following to your vite.config.js:

`js
resolve: {
alias: {
"plotly.js-dist": "plotly.js-basic-dist-min",
lodash: "lodash-es",
},
},
`

If you don't use Vite, or this approach doesn't work for you, you can also use the libPlotly prop of the Plotly component:

`svelte



`

Using FontAwesome icons


Plotly allows you to modify the chart's _mode bar_ (ie. the buttons in the chart's top right corner). However, you can't use any svelte component – it must be an icon in Plotly's specified format. This library includes a helper function faToPlotly that converts a FontAwesome icon to exactly what Plotly needs.

`svelte


config={{
modeBarButtonsToAdd: [
{
name: 'fullscreen',
title: fullscreen ? 'Disable Fullscreen' : 'Enable Fullscreen',
icon: fullscreen ? faToPlotly(faCompress) : faToPlotly(faExpand),
click: () => (fullscreen = !fullscreen)
}
],
}}
...
/>
`

Properties

| Prop | Type | Description |
| -------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| required data | Data[] | array of trace data, see https://plot.ly/javascript/reference/ |
| layout | Partial | layout of the plot, see https://plot.ly/javascript/reference/#layout |
| config | Partial | configuration, see https://plot.ly/javascript/configuration-options/ |
| class | string | class that will be passed to the HTML element wrapping the plot |
| fillParent | boolean \| 'width' \| 'height' | automatically resize the plot to fill the width and/or height of its parent element |
| debounce | number \| DebounceOptions | debounce all changes to the plot |
| libPlotly | Plotly \| null \| undefined | an alternative Plotly bundle to use; if undefined, it defaults to the plotly.js-dist package; if null, no plot will be drawn and no library will be downloaded |
| configReactivityStrategy | 'none' \| 'static-plot' | walkaround for an upstream bug causing config not to update, enabled by default |
| bind:element | HTMLDivElement | the HTML element wrapping the plot |
| bind:plot | PlotlyHTMLElement | the inner HTML element containing the plot |

Events

_NOTE: Due to Plotly's atrocious documentation, most events aren't even mentioned anywhere. Links to source code are provided as the bare minimum information about each event._

| Prop | Callback argument | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| on:afterExport | — | ? |
| on:afterPlot | — | triggers each time a chart is plotted, or re-plotted after the restyling or relayout of a plot (docs), (src) |
| on:animated | — | triggers once an animation finished playing (demo), (docs), (src 1), (src 2) |
| on:animating | — | ? (src) |
| on:animatingFrame | FrameAnimationEvent | ? (src) |
| on:animationInterrupted | — | ? (src) |
| on:autoSize | — | ? (docs) |
| on:beforeExport | — | ? |
| on:beforeHover | PlotMouseEvent | ? |
| on:beforePlot | BeforePlotEvent | ? (src) |
| on:buttonClicked | ButtonClickedEvent | ? |
| on:click | PlotMouseEvent | ? (docs 1), (docs 2) |
| on:clickAnnotation | ClickAnnotationEvent | ? |
| on:deselect | — | ? (docs) |
| on:doubleClick | — | ? (docs) |
| on:framework | — | ? |
| on:hover | PlotHoverEvent | ? (docs) |
| on:legendClick | LegendClickEvent | ? (docs) |
| on:legendDoubleClick | LegendClickEvent | ? (docs) |
| on:react | PlotUpdateEvent | ? |
| on:redraw | — | ? (docs) |
| on:relayout | PlotRelayoutEvent | ? (docs) |
| on:relayouting | PlotRelayoutEvent | ? (docs) |
| on:restyle | PlotRestyleEvent | ? (docs) |
| on:selected | PlotSelectionEvent | ? (docs) |
| on:selecting | PlotSelectionEvent | ? (docs) |
| on:sliderChange | SliderChangeEvent | ? |
| on:sliderEnd | SliderEndEvent | ? |
| on:sliderStart | SliderStartEvent | ? |
| on:sunburstClick | SunburstClickEvent | ? |
| on:transitioned | — | ? |
| on:transitioning | — | ? |
| on:transitionInterrupted | — | ? |
| on:unhover | PlotMouseEvent | ? |
| on:update | PlotUpdateEvent | ? |
| on:webGLContextLost` | — | ? (docs) |

Roadmap

- [x] add autosizing
- [x] add debouncing
- [x] add event redirecting
- [ ] add unit tests
- [ ] add SSR rendering to an image