A component library of 26 charts for Svelte and SvelteKit.
## [Documentation with StackBlitz examples](https://charts.carbondesignsystem.com/)
## Maintenance & support
These Svelte wrappers were developed by Eric Liu.
Please direct all questions regarding support, bug fixes and feature requests to
[@nstuyvesant](https://github.com/nstuyvesant) and [@metonym](https://github.com/metonym).
## Getting started
Run the following command using [npm](https://www.npmjs.com/):
```bash
npm install -D @carbon/charts-svelte
```
If you prefer [Yarn](https://yarnpkg.com/en/), use the following command instead:
```bash
yarn add -D @carbon/charts-svelte
```
The required styles should be imported from `@carbon/charts-svelte/styles.css`.
A release in the near future will move components to runes mode for Svelte 5 and beyond. As this would be a breaking change because event handlers will change to component properties, this version will be published with the distribution tag `next`. Please check here to see if a version for `latest` has been published.
### SvelteKit
While this component library can be used with any build environments for Svelte,
[SvelteKit](https://kit.svelte.dev) is the official framework for building Svelte apps supporting
client-side and server-side rendering (SSR). SvelteKit is powered by [Vite](https://vitejs.dev).
The module `@carbon/charts` should not be externalized for SSR when building for production.
```js
// 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`.
```js
import '@carbon/charts-svelte/styles.css'
```
### Basic
```svelte
```
### 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
```svelte
```
### Dynamic import
Dynamically import a chart and instantiate it using the
[svelte:component API](https://svelte.dev/docs/special-elements#svelte-component). By importing
`@carbon/charts` within `onMount()`, you avoid problems with server-side rendering.
```svelte
```
### Event listeners
In this example, an event listener is attached to the `BarChartSimple` component that fires when
hovering over a bar.
```svelte
```
## Svelte and TypeScript support
Svelte 3.31 or greater is required to use this library with TypeScript. Svelte 5.20+ is
recommended.
### Enums and types
For your convenience, enums and types from `@carbon/charts` are re-exported from
`@carbon/charts-svelte`.
```ts
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.
```ts
import { onMount, type ComponentType } from 'svelte'
import type { BarChartSimple } from '@carbon/charts-svelte'
let component: ComponentType = 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](https://www.typescriptlang.org/docs/handbook/2/indexed-access-types.html) to
extract types for individual properties.
```ts
import { type ComponentProps } from 'svelte'
import { BarChartSimple } from '@carbon/charts-svelte'
type ChartProps = ComponentProps
// 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](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
For more information on the data being collected, please see the
[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).
