@carbon/charts-svelte

Carbon Charts Svelte

A component library of 26 charts for Svelte and SvelteKit.

Documentation with StackBlitz examples

Maintenance & support

These Svelte wrappers were developed by Eric Liu.

Please direct all questions regarding support, bug fixes and feature requests to @nstuyvesant and @metonym.

Getting started

Run the following command using npm:

npm install -D @carbon/charts-svelte

If you prefer Yarn, use the following command instead:

yarn add -D @carbon/charts-svelte

The required styles should be imported from @carbon/charts-svelte/styles.css.

SvelteKit

While this component library can be used with any build environments for Svelte, SvelteKit is the official framework for building Svelte apps supporting client-side and server-side rendering (SSR). SvelteKit is powered by Vite.

The module @carbon/charts should not be externalized for SSR when building for production.

// vite.config.mjs
import { sveltekit } from '@sveltejs/kit/vite'

/** @type {import('vite').UserConfig} */
const config = {
	plugins: [sveltekit()],
	ssr: {
		noExternal: process.env.NODE_ENV === 'production' ? ['@carbon/charts'] : []
	}
}

export default config

Circular dependency warnings

You may see circular dependency warnings for d3 packages. These can be safely ignored.

Usage

Styles must be imported from @carbon/charts-svelte/styles.css or @carbon/charts-svelte/scss.

import '@carbon/charts-svelte/styles.css'

Basic

<script>
	import '@carbon/charts-svelte/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={{
		theme: 'g90',
		title: 'Simple bar (discrete)',
		height: '400px',
		axes: {
			left: { mapsTo: 'value' },
			bottom: { mapsTo: 'group', scaleType: 'labels' }
		}
	}} />

Dispatched events

Each Svelte chart component dispatches the following events:

• on:load: fired when the chart is instantiated
• on:update: fired when data or options are updated
• on:destroy: fired when the component is unmounted and the chart is destroyed

<BarChartSimple {data} {options} on:load on:update on:destroy />

Dynamic import

Dynamically import a chart and instantiate it using the svelte:component API. By importing @carbon/charts within onMount(), you avoid problems with server-side rendering.

<script>
	import '@carbon/charts-svelte/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={{
		theme: 'white',
		title: 'Simple bar (discrete)',
		height: '400px',
		axes: {
			left: { mapsTo: 'value' },
			bottom: { mapsTo: 'group', scaleType: 'labels' }
		}
	}} />

Event listeners

In this example, an event listener is attached to the BarChartSimple component that fires when hovering over a bar.

<script>
	import '@carbon/charts-svelte/styles.css'
	import { onMount } from 'svelte'
	import { BarChartSimple } from '@carbon/charts-svelte'

	let chart

	function barMouseOver(e) {
		console.log(e.detail)
	}

	onMount(() => {
		chart.services.events.addEventListener('bar-mouseover', barMouseOver)

		return () => {
			chart?.services.events.removeEventListener('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' }
		}
	}} />

TypeScript support

Svelte version 3.31 or greater is required to use this library with TypeScript. Svelte 4.x+ is recommended.

Enums and types

For your convenience, enums and types from @carbon/charts are re-exported from @carbon/charts-svelte.

import { ScaleTypes, type BarChartOptions } from '@carbon/charts-svelte'

const options: BarChartOptions = {
	title: 'Simple bar (discrete)',
	height: '400px',
	axes: {
		left: { mapsTo: 'value' },
		bottom: {
			mapsTo: 'group',
			scaleType: ScaleTypes.LABELS
		}
	}
}

Component type

Use the ComponentType utility type from svelte to extract the component type for chart components.

import { onMount, type ComponentType } from 'svelte'
import type { BarChartSimple } from '@carbon/charts-svelte'

let component: ComponentType<BarChartSimple> = null

onMount(async () => {
	component = (await import('@carbon/charts-svelte')).BarChartSimple
})

Component props

Use the ComponentProps utility type from svelte to extract the props for chart components.

You can then use an indexed access type to extract types for individual properties.

import { type ComponentProps } from 'svelte'
import { BarChartSimple } from '@carbon/charts-svelte'

type ChartProps = ComponentProps<BarChartSimple>

// Indexed access type to access the type of the `chart` property
let chart: ChartProps['chart'] = null

IBM Telemetry

This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing this package as a dependency you are agreeing to telemetry collection. To opt out, see Opting out of IBM Telemetry data collection. For more information on the data being collected, please see the IBM Telemetry documentation.