This version is in beta & relies on Carbon v11. If you're using Carbon v10, see the legacy demo site
Carbon Charting Svelte Wrappers
These Svelte wrappers have been developed by Eric Liu.
Please direct all questions regarding support, bug fixes, and feature requests to @metonym.
Run the following command using npm:
npm install -D @carbon/charts-svelte d3
If you prefer Yarn, use the following command instead:
yarn add -D @carbon/charts-svelte d3
Note: you'd also need to install carbon-components
if you're not using a
bundled version of the library.
This is an overview of using Carbon Charts with common Svelte set-ups.
SvelteKit is fast becoming the de facto framework for building Svelte apps that supports both client-side rendering (CSR) and server-side rendering (SSR).
For set-ups powered by vite, add
@carbon/charts
to the list of dependencies for vite
to optimize.
If using a SvelteKit adapter, instruct
vite
to avoid externalizing @carbon/charts
when building for production.
// svelte.config.js
import adapter from '@sveltejs/adapter-node';
const production = process.env.NODE_ENV === 'production';
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
adapter: adapter(),
vite: {
optimizeDeps: {
include: ['@carbon/charts'],
},
ssr: {
noExternal: [production && '@carbon/charts'].filter(Boolean),
},
},
},
};
export default config;
vite-plugin-svelte is an
alternative to using SvelteKit. Similarly, instruct vite
to optimize
@carbon/charts
in vite.config.js.
Note that @sveltejs/vite-plugin-svelte
is the official vite/svelte integration
not to be confused with svite.
// vite.config.js
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';
export default defineConfig(({ mode }) => {
return {
plugins: [svelte()],
build: { minify: mode === 'production' },
optimizeDeps: { include: ['@carbon/charts'] },
};
});
sapper is another official Svelte framework that supports server-side rendering (SSR).
Take care to install @carbon/charts-svelte
as a development dependency.
No additional configuration should be necessary.
Install and add
@rollup/plugin-replace
to the list of plugins in rollup.config.js
to avoid the
process is not defined
runtime error.
This plugin statically replaces strings in bundled files with the specified value.
In the example below, all instances of process.env.NODE_ENV
will be replaced
with "production"
while bundling.
// rollup.config.js
import replace from '@rollup/plugin-replace';
export default {
// ...
plugins: [
replace({
preventAssignment: true,
'process.env.NODE_ENV': JSON.stringify('production'),
}),
],
};
Set context: "window"
to address the
this has been rewritten to undefined
Rollup error.
export default {
+ context: "window",
};
You may see circular dependency warnings for d3
and @carbon/charts
packages
that can be safely ignored.
Use the onwarn
option to selectively ignore these warnings.
// rollup.config.js
export default {
onwarn: (warning, warn) => {
// omit circular dependency warnings emitted from
// "d3-*" packages and "@carbon/charts"
if (
warning.code === 'CIRCULAR_DEPENDENCY' &&
/^node_modules\/(d3-|@carbon\/charts)/.test(warning.importer)
) {
return;
}
// preserve all other warnings
warn(warning);
},
};
If using dynamic imports, set
inlineDynamicImports: true
in rollup.config.js
to enable code-splitting.
Otherwise, you may encounter the Rollup error
Invalid value "iife" for option "output.format" - UMD and IIFE output formats are not supported for code-splitting builds.
export default {
+ inlineDynamicImports: true,
};
webpack is another popular application bundler used to build Svelte apps.
No additional configuration should be necessary.
snowpack is an ESM-powered frontend build tool.
Ensure you have
@snowpack/plugin-svelte
added as a plugin in snowpack.config.js
.
No additional configuration should be necessary.
// snowpack.config.js
/** @type {import("snowpack").SnowpackUserConfig } */
module.exports = {
plugins: ['@snowpack/plugin-svelte'],
};
Styles must be imported from both @carbon/charts
and @carbon/styles
.
import '@carbon/styles/css/styles.css';
import '@carbon/charts/styles.css';
<script>
import "@carbon/styles/css/styles.css";
import "@carbon/charts/styles.css";
import { BarChartSimple } from "@carbon/charts-svelte";
</script>
<BarChartSimple
data={[
{ group: "Qty", value: 65000 },
{ group: "More", value: 29123 },
{ group: "Sold", value: 35213 },
{ group: "Restocking", value: 51213 },
{ group: "Misc", value: 16932 },
]}
options={{
title: "Simple bar (discrete)",
height: "400px",
axes: {
left: { mapsTo: "value" },
bottom: { mapsTo: "group", scaleType: "labels" },
},
}}
/>
@carbon/styles
uses
CSS custom properties
for dynamic, client-side theming. Update the Carbon theme using the theme
prop.
Supported themes include:
"white"
"g10"
(Gray 10)"g90"
(Gray 90)"g100"
(Gray 100)
The default theme is "white"
.
<BarChartSimple
theme="g90"
data={/* ... */}
options={/* ... */}
/>
Each Svelte chart component dispatches the following events:
- on:load: fired when the chart is instantiated
- on:update: fired when
data
oroptions
are updated - on:destroy: fired when the component is unmounted and the chart is destroyed
<BarChartSimple
{data}
{options}
on:load
on:update
on:destroy
/>
Dynamically import a chart and instantiate it using the svelte:component API.
<script>
import "@carbon/styles/css/styles.css";
import "@carbon/charts/styles.css";
import { onMount } from "svelte";
let chart;
onMount(async () => {
const charts = await import("@carbon/charts-svelte");
chart = charts.BarChartSimple;
});
</script>
<svelte:component
this={chart}
data={[
{ group: "Qty", value: 65000 },
{ group: "More", value: 29123 },
{ group: "Sold", value: 35213 },
{ group: "Restocking", value: 51213 },
{ group: "Misc", value: 16932 },
]}
options={{
title: "Simple bar (discrete)",
height: "400px",
axes: {
left: { mapsTo: "value" },
bottom: { mapsTo: "group", scaleType: "labels" },
},
}}
/>
In this example, an event listener is attached to the BarChartSimple
component
that fires when hovering over a bar.
<script>
import "@carbon/styles/css/styles.css";
import "@carbon/charts/styles.css";
import { onMount } from "svelte";
import { BarChartSimple } from "@carbon/charts-svelte";
let chart;
function barMouseOver(e) {
console.log(e.detail);
}
onMount(() => {
return () => {
if (chart) chart.services.events.removeEventListener("bar-mouseover", barMouseOver);
};
});
$: if (chart) chart.services.events.addEventListener("bar-mouseover", barMouseOver);
</script>
<BarChartSimple
bind:chart
data={[
{ group: "Qty", value: 65000 },
{ group: "More", value: 29123 },
{ group: "Sold", value: 35213 },
{ group: "Restocking", value: 51213 },
{ group: "Misc", value: 16932 },
]}
options={{
title: "Simple bar (discrete)",
height: "400px",
axes: {
left: { mapsTo: "value" },
bottom: { mapsTo: "group", scaleType: "labels" },
},
}}
/>
Sample use cases can be seen here.
When opening the link above, click on the Edit on Codesandbox button for each demo to see an isolated project showing you how to reproduce the demo.
Although we will definitely introduce new models in the future as we start shipping new components such as maps, Data and options follow the same model in all charts, with minor exceptions and differences in specific components.
For instance in the case of a donut chart you're able to pass in an additional
field called center
in your options configuring the donut center.
For instructions on using the tabular data format, see here
There are also additional options available depending on the chart type being used, see our demo examples here.
Customizable options (specific to chart type) can be found here
Svelte version 3.31 or greater is required to use this library with TypeScript.
TypeScript definitions are located in the types folder.