Carbon Components Svelte is a Svelte component library that implements the Carbon Design System, an open source design system by IBM. Ship accessible, consistent, production-ready interfaces.
100+ components: from inputs to data tables
5 built-in themes: two light, three dark
Fully typed TypeScript API: props, events, and slots
Each precompiled StyleSheet contains the styles for every component. To ship only the styles your app uses, add optimizeCss to your production build. Set propAware: true to also drop the styles of prop values your app never passes; see prop-aware pruning.
The SCSS sources are not published. Compiling carbon-components v10 SCSS yourself misses styles for components and variants that only this library provides.
Dynamic theming
To switch themes at runtime, import the combined "all.css" StyleSheet instead of a single theme. It bundles all five themes and toggles between them through a theme attribute on the HTML element.
import "carbon-components-svelte/css/all.css";
Update the theme by setting the theme attribute on the html element. The default theme is "white".
carbon-preprocess-svelte is a collection of Svelte preprocessors and build plugins for Carbon. It trims build times and bundle size with three drop-in tools: faster compiles in development, leaner CSS and leaner JavaScript when you ship. Each works on its own.
[!NOTE]
Using carbon-preprocess-svelte is optional and not a prerequisite for this library. It should be installed as a development dependency.
Rewrites Carbon components for the props your app passes, removing code it never runs
optimizeImports
optimizeImports is a Svelte preprocessor that rewrites barrel imports from Carbon components/icons/pictograms packages to their source Svelte code paths. This can significantly speed up development and production build compile times while preserving typeahead and autocompletion offered by integrated development environments (IDE) like VS Code.
The preprocessor optimizes imports from the following packages:
- import { Button } from "carbon-components-svelte";+ import Button from "carbon-components-svelte/src/Button/Button.svelte";- import { Add } from "carbon-icons-svelte";+ import Add from "carbon-icons-svelte/lib/Add.svelte";- import { Airplane } from "carbon-pictograms-svelte";+ import Airplane from "carbon-pictograms-svelte/lib/Airplane.svelte";
optimizeCss
optimizeCss is a build plugin that removes unused Carbon styles at build time, often removing hundreds of kilobytes from production bundles. It runs on Vite, Rollup, and Rolldown. For Webpack and Rspack, use OptimizeCssPlugin.
carbon-components-svelte@0.85.0 or greater is required.
[!NOTE]
This is a plugin and not a Svelte preprocessor. Add it to your bundler's plugins. Vite runs it on vite build only, and OptimizeCssPlugin runs in Webpack's production mode only. Under Rollup and Rolldown, add it to production builds only.
Prop-aware pruning
Set propAware: true to also remove styles for the prop values your app never passes.
optimizeCss({ propAware: true });
<Button kind="tertiary">Save</Button><!-- kept: .bx--btn, .bx--btn--tertiary pruned: the other kinds and sizes, .bx--skeleton, the icon-only tooltip -->
It reads literal props, constants and state nothing reassigns (including constants your own modules export), your own wrapper components, props forwarded with {...$$restProps} or ...rest, object and array literals, and your own {#if} and {#each}. A value it can't read keeps every variant: a reassigned variable, a writable store, bind:, a spread of anything but a literal or forwarded props, or data fetched at runtime.
optimizeComponents rewrites each Carbon component your app renders for the props it passes. Values that never change become literals, and branches that can't run are removed, along with child components only those branches render (a skeleton, a tooltip portal). It is the JavaScript counterpart of prop-aware CSS pruning and uses the same analysis. In typical apps it removes 18–27% of the production JavaScript.
Your own wrapper components are rewritten the same way when every place that renders them is in content.
add optimizeComponents() to vite.plugins; it orders itself first
vite build only, never vite dev
Rollup, Rolldown
list optimizeComponents() before the Svelte plugin
production builds only (add it conditionally)
Webpack, Rspack
add new OptimizeComponentsPlugin() to plugins
mode: "production" only
It analyzes the files matched by content (default: source files under src/) before the build. If a module outside content renders a Carbon component, or one of your rewritten wrappers, including through a re-export or a dynamic import(), the build fails instead of shipping wrong code.
Wrappers imported through an alias ($lib/Card.svelte, #lib/Card.svelte) are resolved with the bundler's own resolver.
SvelteKit and Astro server and client builds are rewritten alike, so prerendered pages hydrate as before.
Set report: true to print what each build rewrote.
<script> import Cloud from "carbon-pictograms-svelte/lib/Cloud.svelte";</script><Cloud />
Documentation for LLMs
Documentation is available in LLM-friendly plain text for use with coding assistants, plus a standalone Markdown document for every component. Append .md to any component's URL to read it.
llms.txt: a component index where each entry links to its per-component Markdown doc, sized for model context windows.
llms-full.txt: the full component documentation in a single plain-text file.
This package uses IBM Telemetry to collect de-identified and anonymized metrics data in CI environments. 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.
