carbon-components-svelte Documentation

Technical Documentation: carbon-design-system/carbon-components-svelte

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

carbon-components-svelte

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
• WCAG 2.1 AA: keyboard and screen-reader ready

The Carbon Svelte ecosystem also includes:

• Carbon Icons Svelte: 2,700+ Carbon icons as Svelte components
• Carbon Pictograms Svelte: 1,500+ Carbon pictograms as Svelte components
• Carbon Charts Svelte: 25+ charts, powered by d3
• Carbon Preprocess Svelte: Svelte preprocessors and build plugins for Carbon

[Documentation](https://svelte.carbondesignsystem.com) Copy Chapter

Installation Copy Chapter

# npm
npm i carbon-components-svelte

# pnpm
pnpm add carbon-components-svelte

# Yarn
yarn add carbon-components-svelte

# Bun
bun add carbon-components-svelte

Usage Copy Chapter

Styling Copy Section

Before importing components, you will need to first apply Carbon component styles. The Carbon Design System supports five themes (2 light, 3 dark).

• white.css: Default Carbon theme (light)
• g10.css: Gray 10 theme (light)
• g80.css: Gray 80 theme (dark)
• g90.css: Gray 90 theme (dark)
• g100.css: Gray 100 theme (dark)
• all.css: All five themes (White, Gray 10, Gray 80, Gray 90, Gray 100) using CSS variables

Each StyleSheet is compiled from Carbon v10 SCSS ([email protected], vendored) and this library's own partials in css.

The compiled CSS is generated from the following .scss files:

• css/white.scss
• css/g10.scss
• css/g80.scss
• css/g90.scss
• css/g100.scss
• css/all.scss

Import one theme once at the top-level entry point of your app, like index.js or src/+layout.svelte.

CSS StyleSheet

// White theme
import "carbon-components-svelte/css/white.css";

// Gray 10 theme
import "carbon-components-svelte/css/g10.css";

// Gray 80 theme
import "carbon-components-svelte/css/g80.css";

// Gray 90 theme
import "carbon-components-svelte/css/g90.css";

// Gray 100 theme
import "carbon-components-svelte/css/g100.css";

// All themes
import "carbon-components-svelte/css/all.css";

Smaller CSS Copy Section

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 Copy Section

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".

<!doctype html>
<html lang="en" theme="g10">
  <body>
    ...
  </body>
</html>

Or programmatically switch between each of the five Carbon themes by setting the theme attribute on the HTML element.

<script>
  let theme = "white"; // "white" | "g10" | "g80" | "g90" | "g100"

  $: document.documentElement.setAttribute("theme", theme);
</script>

Alternatively, use the Theme component to manage the theme reactively.

Importing components Copy Section

Import components from carbon-components-svelte in the script tag of your Svelte file. Visit the documentation site for examples.

<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion>
  <AccordionItem title="Section 1" open> Content 1 </AccordionItem>
  <AccordionItem title="Section 2"> Content 2 </AccordionItem>
  <AccordionItem title="Section 3"> Content 3 </AccordionItem>
</Accordion>

Refer to the documentation site for component API documentation.

Preprocessors & Plugins Copy Chapter

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.

# npm
npm i -D carbon-preprocess-svelte

# pnpm
pnpm add -D carbon-preprocess-svelte

# Yarn
yarn add -D carbon-preprocess-svelte

# Bun
bun add -D carbon-preprocess-svelte

`optimizeImports` Copy Section

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:

• carbon-components-svelte
• carbon-icons-svelte
• carbon-pictograms-svelte

Before & After

- 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` Copy Section

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.

[email protected] or greater is required.

$ vite build

Optimized assets/index-Doxsm5Yz.css
- Before: 557.37 kB
+ After:   46.16 kB (-91.72%)

dist/index.html                  0.33 kB │ gzip:  0.23 kB
dist/assets/index-Doxsm5Yz.css  46.16 kB │ gzip:  6.12 kB
dist/assets/index-BoBcXTHi.js   69.61 kB │ gzip: 24.35 kB

[!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>

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.

Refer to the carbon-preprocess-svelte documentation for details.

`optimizeComponents` Copy Section

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.

// vite.config.js
import { svelte } from "@sveltejs/vite-plugin-svelte";
import {
  optimizeComponents,
  optimizeCss,
  optimizeImports,
} from "carbon-preprocess-svelte";

export default {
  plugins: [
    optimizeComponents(),
    svelte({ preprocess: [optimizeImports()] }),
    optimizeCss({ propAware: true }),
  ],
};

• 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.

Refer to the carbon-preprocess-svelte documentation for every option.

Configure your bundler Copy Section

Add optimizeImports to your Svelte preprocessor and optimizeCss to your bundler plugins. See examples for full configurations.

Vite

// vite.config.js
import { svelte, vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";

export default {
  plugins: [
    svelte({
      preprocess: [vitePreprocess(), optimizeImports()],
    }),
    optimizeCss(),
  ],
};

SvelteKit

// vite.config.js
import adapter from "@sveltejs/adapter-static";
import { sveltekit } from "@sveltejs/kit/vite";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";

export default {
  plugins: [
    sveltekit({
      preprocess: [vitePreprocess(), optimizeImports()],
      adapter: adapter(),
    }),
    optimizeCss(),
  ],
};

On SvelteKit 2, pass the same preprocess in svelte.config.js and the adapter under kit.

Rollup

// rollup.config.js
import svelte from "rollup-plugin-svelte";
import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";

const production = !process.env.ROLLUP_WATCH;

export default {
  plugins: [
    svelte({
      preprocess: [optimizeImports()],
    }),
    production && optimizeCss(),
  ],
};

Webpack

Rspack implements Webpack's plugin and loader APIs, so the same configuration works in rspack.config.mjs.

// webpack.config.mjs
import { OptimizeCssPlugin, optimizeImports } from "carbon-preprocess-svelte";

export default {
  module: {
    rules: [
      {
        test: /\.svelte$/,
        use: {
          loader: "svelte-loader",
          options: {
            preprocess: [optimizeImports()],
          },
        },
      },
    ],
  },
  plugins: [new OptimizeCssPlugin()],
};

Icons and pictograms Copy Chapter

The icon and pictogram sets ship as separate packages of individual Svelte components. Each is optional, so install only what you need.

Icons Copy Section

2,700+ icons designed for product UI, in four sizes (16, 20, 24, and 32 pixels), set with a single prop.

# npm
npm i carbon-icons-svelte

# pnpm
pnpm add carbon-icons-svelte

# Yarn
yarn add carbon-icons-svelte

# Bun
bun add carbon-icons-svelte

<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Add size={24} />

Pictograms Copy Section

1,500+ illustrative pictograms for empty states, onboarding, hero sections, and feature callouts. Larger than icons, 64px by default.

# npm
npm i carbon-pictograms-svelte

# pnpm
pnpm add carbon-pictograms-svelte

# Yarn
yarn add carbon-pictograms-svelte

# Bun
bun add carbon-pictograms-svelte

<script>
  import Cloud from "carbon-pictograms-svelte/lib/Cloud.svelte";
</script>

<Cloud />

Documentation for LLMs Copy Chapter

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.

Examples Copy Chapter

• examples/rollup
• examples/sveltekit
• examples/vite
• examples/webpack

TypeScript support Copy Chapter

Every component ships TypeScript definitions for its props, events, and slots (src/**/*.svelte.d.ts), generated from the component source by sveld.

Contributing Copy Chapter

Refer to the Contributing guidelines.

[Changelog](CHANGELOG.md) Copy Chapter

License Copy Chapter

Apache 2.0

IBM Telemetry Copy Chapter

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.

Overview (`thumbnails/README.md`) Copy Section

Thumbnails

Every component with a docs page gets a 320×180 SVG here, named after
the page in kebab case (ToggleButtonGroup.svx →
toggle-button-group.svg). carbon.yml points at these through
thumbnailPath, and they're the preview a catalog shows next to the
component name.

New components usually ship without one, and without the carbon.yml
entry that makes the catalog show it. Check both before each release.

Find what's missing Copy Chapter

bun run thumbnails missing

It keys off the docs pages, not src/. Pages like ClickableTile live
inside another folder (src/Tile/), and folders like ListBox or
FormItem have no page. It also lists thumbnails with no page, except
tabs-vertical.svg, which backs the tabs-vertical catalog entry
(TabsVertical is documented on the Tabs page). Any other thumbnail with
no page is for a component that doesn't exist; delete it.

missing doesn't read carbon.yml. catalog does, and exits non-zero
on any gap between it, the docs pages, and thumbnails/:

bun run thumbnails catalog

It lists docs pages with no asset, assets whose thumbnailPath file is
missing, thumbnails no asset uses, and names that aren't sentence case
or don't spell the asset's key or docs page (it would have caught
"Tootlip icon"). Assets without a name inherit it from carbon-styles
and skip the name checks. A page deliberately left out of the catalog
goes in UNCATALOGED_PAGES in scripts/lib/thumbnails.ts, with a line
here saying why. None are left out today.

scripts/thumbnails.ts has three more commands, used in the
recipe: audit checks the mechanical rules below, sheet
renders a contact sheet, and themes renders the files in all five
themes.

Design principles Copy Chapter

A thumbnail is a glyph, not a screenshot. People see it at a fraction
of its size in a grid full of others, so it has one job: make the
component recognizable and tell it apart from its neighbors.

One idea per thumbnail. Pick the single trait that defines the
component and draw only that. Meter is a track with a fill in a status
color. It isn't three meters in three states with threshold ticks. If
you're listing features, cut. The first draft is almost always too
busy.

Abstract by default. Text is a flat bar, not words. Media is a
filled block. Icons appear only when they carry the meaning (bold,
italic, and underline in ToggleButtonGroup, chevrons on Carousel
controls).

Real text only when the text is the component. Link, Text,
RelativeTime, and Truncate show literal words, because "2 days ago"
says more than any shape could. Keep it to a short phrase. A list is
not its text: OrderedList is bars with numbers, not "Ordered List"
four times.

Distinguish from look-alikes. Before drawing, find the existing
thumbnail it could be mistaken for and pick the trait that separates
them. Meter and ProgressBar are both a labeled track. Meter's warning
yellow fill is the difference, and ProgressBar keeps the blue. The
likeliest look-alikes sit in the same docs category, so render that
category's sheet (bun run thumbnails sheet --category Layout).

Show invisible structure with dashed outlines. Some components are
about something you can't see: rows that aren't rendered
(VirtualList), padding that content breaks out of (Bleed). A dashed
text-disabled outline marks a boundary or a thing that isn't there.
Solid shapes are things that render.

Nothing cut off, no chrome. Draw every element whole. Leave out
scrollbars, window frames, and partial rows, even when the real
component has them. A clipped shape reads as a rendering bug at
thumbnail size.

Spend color on the point. Stay in greys and use one accent, either
background-brand blue or a status color, on the element that carries
the idea: the selected tab, the pressed button, the meter fill. Two
accents compete.

Shadows mean "floats above". Only layers that float get a shadow:
menus, popovers, tooltips, modals, toasts. Draw it with the
elevation recipe so every floating layer casts the same
one.

Match the family. Separator rules are 1px border-subtle, the
same as Divider and DescriptionList. Text bars are 6px or 8px tall.
Keep stroke weights, bar heights, and spacing consistent with the
existing set so the grid reads as one system. Reuse the
visual vocabulary for states instead of
inventing a new cue.

Draw symbols at the weight of the bars. The set is flat fills.
A symbol drawn as an outlined illustration, or at twice the size of
the bars beside it, looks pasted in. The first LocalStorage draft had
a 48px stroked database cylinder and read as clip art; outlined
braces at the same weight as the key/value bars fit. Strokes are for
1px borders and dashed boundaries, not for drawing objects.

Fill the safe area. A lone 16px icon in the middle of the canvas
disappears in the grid. A thumbnail that is one control (CopyButton,
BadgeIndicator, Loading) scales it up; see the sizes under
Canvas and geometry.

Twins share one design. Components that come in a pair or family
look alike on purpose and differ in one place. LocalStorage and
SessionStorage are the same braces, with the session one inside a
browser tab. The skeleton family shares one shimmer. The tooltip
family shares one bubble and differs by trigger.

No cursors. A pointer or hand says "interactive" about everything,
so it says nothing. Show the component's own cue instead: an arrow
icon on ClickableTile, a chevron on ExpandableTile. The exception is
ContextMenu, whose idea is a menu that opens at the pointer.

When a symbol doesn't land, change direction. Don't nudge the
size or color of a symbol that reads wrong. Draft three or four
different directions in .context/, render them side by side with
sheet, and pick one. Draft twins as pairs so you judge the
difference between them too.

Break a rule only when breaking it is the idea. ScrollGradient is
about content that runs past the edge, so its rows are cut off.
TagSet is about color variety, so it uses several. If the exception
isn't the component's one idea, the rule holds.

Canvas and geometry Copy Chapter

Center the composition both ways. Measure the bounding box of
everything you drew, not just the main shape.

Visual vocabulary Copy Chapter

The same state should look the same in every thumbnail.

Look-alike pairs and the trait that separates them:

Color tokens Copy Chapter

Every fill and stroke uses var(--cds-<token>, <hex>) so the
thumbnail follows the host theme. The hex is the white-theme value
and is what renders anywhere the variable isn't defined, including
GitHub and rsvg-convert. Reuse these pairs exactly:

The thumbnails theme only when they're inlined into a page that
defines the tokens. Loaded through `` or on GitHub, an SVG is its
own document, so every var() falls back to the hex.

Pick tokens by what they sit on, because some flip in dark themes and
some don't. icon-inverse, layer-02, and background-inverse flip;
text-on-color stays white. A label on a blue button is text-on-color: with
icon-inverse it turns dark on g80, g90, and g100. A check on an
icon-primary checkbox is icon-inverse, so the two flip together.

bun run thumbnails audit fails on any other token or a mismatched
hex. Raw colors fail too, except in thumbnails whose idea is literal
color (tag, tag-set, theme, user-avatar-group; see
RAW_COLOR_EXCEPTIONS in scripts/lib/thumbnails.ts).

To match what the component really renders, read its partial in
css/_<component>.scss and map the Sass token to the closest row
above. For example, _meter.scss fills the warning state with
$support-warning, which is --cds-support-warning.

File template Copy Chapter

<?xml version="1.0" encoding="UTF-8"?>
<svg width="320px" height="180px" viewBox="0 0 320 180" version="1.1" xmlns="http://www.w3.org/2000/svg">
    <title>component-name</title>
    <g id="component-name" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
        <rect id="label" fill="var(--cds-text-disabled, #c6c6c6)" x="76" y="74" width="60" height="8"></rect>
    </g>
</svg>

Give each part an id that names what it is (track, fill,
selected). The ids make the file reviewable without rendering it.

Draw plain shapes. No , , or xlink:href: they're
how design-tool exports reuse geometry, and they make the file harder
to read and edit. Keep each file under 8 KB; a bigger one is usually
outlined text or exported cruft.

Elevation Copy Chapter

A floating layer is two rects with the same geometry: a black one
under the shadow filter, then the surface on top.

<defs>
    <filter id="component-name-shadow" filterUnits="userSpaceOnUse" x="0" y="0" width="320" height="180">
        <feOffset dy="2" in="SourceAlpha" result="offset"></feOffset>
        <feGaussianBlur stdDeviation="3" in="offset" result="blur"></feGaussianBlur>
        <feColorMatrix in="blur" type="matrix" values="0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 0.3 0"></feColorMatrix>
    </filter>
</defs>
<rect id="shadow" fill="black" filter="url(#component-name-shadow)" x="100" y="48" width="120" height="44"></rect>
<rect id="surface" fill="var(--cds-layer-02, #ffffff)" x="100" y="48" width="120" height="44"></rect>

The filter region covers the whole canvas on purpose. A region in
percentages of a short shape is too small for the blur and clips it
into a smear, which is what broke tooltip-icon.svg. The fill="black"
under a filter is the one raw color audit allows.

Recipe Copy Chapter

1. Run bun run thumbnails missing to list missing thumbnails.
2. For each one, read the page's frontmatter description: and its
   ## Basic example. Write down the one trait you'll draw before
   opening an editor.
3. Render the sheet for its docs category
   (bun run thumbnails sheet --category <label>, labels from
   docs/src/component-categories.ts). Note what the neighbors look
   like so the new one doesn't.
4. Copy the closest existing thumbnail as a starting point. The shared
   layout, tokens, and sizes come along for free.
5. Draw it. Check colors against the component's SCSS partial. Keep
   drafts and alternatives in .context/drafts/, not thumbnails/.
   sheet takes paths too:
   bun run thumbnails sheet meter .context/drafts/meter-b.svg.
6. Check the mechanics: bun run thumbnails audit <name>… and
   xmllint --noout thumbnails/<name>.svg.
7. Check themes: bun run thumbnails themes <name>… renders the
   files in white, g10, g80, g90, and g100 to
   .context/thumbnails-themes.png. It needs a built css/all.css
   (bun run build:css). Look for marks that vanish or invert against
   their fill.
8. Review: bun run thumbnails sheet <name>… writes
   .context/thumbnails-sheet.png. Seeing the new ones side by side
   catches inconsistent weight and spacing that a single render hides.
   Check each against the principles above, and cut whatever isn't
   the one idea.
9. Commit as chore: add thumbnail SVGs for <components>.
10. Add a carbon.yml entry for each new thumbnail, in a separate
    commit (chore: add <components> to carbon.yml). See
    Catalog entries.

For a cleanup that shouldn't change the picture (renaming ids,
inlining ``, swapping a raw hex for its token), render every
touched file before and after and compare the pixels. Visual review
misses one-pixel shifts and dropped shadows; a diff doesn't.

Catalog entries Copy Chapter

carbon.yml lists one asset per component under assets:, keyed by the
thumbnail name and kept in alphabetical order. A component that Carbon
also ships inherits its name and description from carbon-styles, so its
entry only adds thumbnailPath, externalDocsUrl, and the demo link. A
Svelte-only component spells everything out:

table-of-contents:
    name: Table of contents
    status: stable
    type: component
    platform: web
    framework: svelte
    thumbnailPath: './thumbnails/table-of-contents.svg'
    demoLinks:
      - type: other
        name: Documentation
        action: link
        url: https://svelte.carbondesignsystem.com/components/TableOfContents

name is the page name in Carbon's sentence case: "Toggle button group",
not "Toggle Button Group". Acronyms stay upper case ("UI shell header",
"PIN code input"), and Carbon's one-word names stay one word
("Multiselect", "Toggletip"). A component documented inside
another page links to that page's section, as tabs-vertical links to
Tabs#vertical. Check it with bun run thumbnails catalog, which also fails if the file
doesn't parse.

Gotchas Copy Chapter

Content Overview (`docs/content/overview.md`) Copy Section

A complete Svelte component library that implements the IBM Carbon Design System. 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
• WCAG 2.1 AA — keyboard and screen-reader ready

Quick start Copy Chapter

Install the library, pick a theme, and render your first component. Three steps to a running app, plus customization options below.

1. Install the package Copy Section

# npm
npm i carbon-components-svelte

# pnpm
pnpm add carbon-components-svelte

# Yarn
yarn add carbon-components-svelte

# Bun
bun add carbon-components-svelte

2. Apply a theme stylesheet Copy Section

Import one precompiled Carbon theme. The Carbon Design System supports five themes (2 light, 3 dark): White, Gray 10, Gray 80, Gray 90, Gray 100.

Import this once at the top-level, like index.js or src/+layout.svelte.

// White theme
import "carbon-components-svelte/css/white.css";

// Gray 10 theme
import "carbon-components-svelte/css/g10.css";

// Gray 80 theme
import "carbon-components-svelte/css/g80.css";

// Gray 90 theme
import "carbon-components-svelte/css/g90.css";

// Gray 100 theme
import "carbon-components-svelte/css/g100.css";

// All themes (for dynamic theming)
import "carbon-components-svelte/css/all.css";

3. Import a component Copy Section

<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button>Hello Carbon</Button>

Explore the full component index.

Dynamic theming Copy Chapter

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 the stylesheet once, at the top-level entry point of your app:

import "carbon-components-svelte/css/all.css";

Then set the theme reactively in Svelte:

<script>
  let theme = "white"; // "white" | "g10" | "g80" | "g90" | "g100"

  $: document.documentElement.setAttribute("theme", theme);
</script>

Or statically in your HTML:

<html theme="white"></html>

Or use the Theme component to manage the theme reactively.

Faster builds, smaller bundles Copy Chapter

The fast path is enough to build. carbon-preprocess-svelte trims build times and bundle size with three drop-in tools: faster HMR in development, and leaner CSS and JavaScript when you ship. Each works on its own.

Add carbon-preprocess-svelte as a dev dependency:

# npm
npm i -D carbon-preprocess-svelte

# pnpm
pnpm add -D carbon-preprocess-svelte

# Yarn
yarn add -D carbon-preprocess-svelte

# Bun
bun add -D carbon-preprocess-svelte

optimizeImports Copy Section

Rewrites barrel imports to direct source paths, dramatically cutting cold build and HMR times.

optimizeCss Copy Section

Tree-shakes unused Carbon CSS at build time, often removing hundreds of kilobytes from production bundles. In typical apps it removes 60–80% of the stylesheet. Set propAware: true to also remove styles for prop values your app never passes, which removes over 80%.

optimizeComponents Copy Section

Rewrites each Carbon component your app renders for the props it passes, removing branches and child components that can never run. 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. It runs on production builds only, and fails the build if a module outside its content globs renders a Carbon component or a rewritten wrapper, including through a re-export or a dynamic import(). For Webpack and Rspack, use OptimizeComponentsPlugin.

// vite.config.js
import { svelte } from "@sveltejs/vite-plugin-svelte";
import {
  optimizeComponents,
  optimizeCss,
  optimizeImports,
} from "carbon-preprocess-svelte";

export default {
  plugins: [
    optimizeComponents(),
    svelte({ preprocess: [optimizeImports()] }),
    optimizeCss({ propAware: true }),
  ],
};

Configure your bundler Copy Section

Add optimizeImports to your Svelte preprocessor and optimizeCss to your bundler plugins.

Vite:

// vite.config.js
import { svelte, vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";

export default {
  plugins: [
    svelte({
      preprocess: [vitePreprocess(), optimizeImports()],
    }),
    optimizeCss(),
  ],
};

SvelteKit:

// vite.config.js
import adapter from "@sveltejs/adapter-static";
import { sveltekit } from "@sveltejs/kit/vite";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";

export default {
  plugins: [
    sveltekit({
      preprocess: [vitePreprocess(), optimizeImports()],
      adapter: adapter(),
    }),
    optimizeCss(),
  ],
};

On SvelteKit 2, pass the same preprocess in svelte.config.js and the adapter under kit.

Rollup:

// rollup.config.js
import svelte from "rollup-plugin-svelte";
import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";

const production = !process.env.ROLLUP_WATCH;

export default {
  plugins: [
    svelte({
      preprocess: [optimizeImports()],
    }),
    production && optimizeCss(),
  ],
};

Webpack:

Rspack implements Webpack's plugin and loader APIs, so the same configuration works in rspack.config.mjs.

// webpack.config.mjs
import { OptimizeCssPlugin, optimizeImports } from "carbon-preprocess-svelte";

export default {
  module: {
    rules: [
      {
        test: /\.svelte$/,
        use: {
          loader: "svelte-loader",
          options: {
            preprocess: [optimizeImports()],
          },
        },
      },
    ],
  },
  plugins: [new OptimizeCssPlugin()],
};

Icons and pictograms Copy Chapter

The icon and pictogram sets ship as separate packages of individual Svelte components. Both are professionally designed, original iconography crafted to complement the scale and grid of Carbon components. Each is optional, so install only what you need.

Icons Copy Section

2,700+ icons designed for product UI, in four sizes (16, 20, 24, and 32 pixels), set with a single prop.

# npm
npm i carbon-icons-svelte

# pnpm
pnpm add carbon-icons-svelte

# Yarn
yarn add carbon-icons-svelte

# Bun
bun add carbon-icons-svelte

<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Add size={24} />

Pictograms Copy Section

1,500+ illustrative pictograms for empty states, onboarding, hero sections, and feature callouts. Larger than icons, 64px by default.

# npm
npm i carbon-pictograms-svelte

# pnpm
pnpm add carbon-pictograms-svelte

# Yarn
yarn add carbon-pictograms-svelte

# Bun
bun add carbon-pictograms-svelte

<script>
  import Cloud from "carbon-pictograms-svelte/lib/Cloud.svelte";
</script>

<Cloud />

Documentation for LLMs Copy Chapter

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.

Collection Copy Chapter

The Carbon Svelte collection includes packages for icons, pictograms, and data visualization:

• Carbon Components Svelte — 100+ components — GitHub
• Carbon Icons Svelte — 2,700+ icons — GitHub
• Carbon Pictograms Svelte — 1,500+ pictograms — GitHub
• Carbon Charts Svelte — 25+ charts, powered by d3 — GitHub
• Carbon Preprocess Svelte — Svelte preprocessors and build plugins — GitHub

Package.Json (`docs/package.json`) Copy Section

{
"private": true,
"scripts": {
"dev": "bun run format-component-api && bun run --parallel index-docs dev:vite",
"dev:vite": "vite dev",
"build": "bun run format-component-api && bun run --parallel build:index-docs build:sitemap && bun run build:md-docs && bun run build:vite",
"index-docs": "bun scripts/index-docs.ts",
"build:index-docs": "bun scripts/index-docs.ts",
"build:md-docs": "bun scripts/generate-md-docs.ts",
"build:sitemap": "bun scripts/generate-sitemap.ts",
"format-component-api": "bun scripts/format-component-api.ts",
"build:vite": "vite build",
"typecheck:examples": "bun scripts/typecheck-examples.ts",
"preview": "vite preview"
},
"devDependencies": {
"@roxi/routify": "^3.6.4",
"@sveltejs/vite-plugin-svelte": "^7.3.1",
"@types/mdast": "^4.0.4",
"@types/prismjs": "^1.26.5",
"@types/unist": "^3.0.3",
"carbon-icons-svelte": "^13.15.0",
"carbon-pictograms-svelte": "^13.20.0",
"clipboard-copy": "^4.0.1",
"estree-walker": "^3.0.3",
"github-slugger": "^2.0.0",
"mdsvex": "^0.12.8",
"minisearch": "^7.1.0",
"prettier": "^3.9.9",
"prettier-plugin-svelte": "^4.1.1",
"prismjs": "^1.30.0",
"rehype-slug": "^6.0.0",
"svelte": "^5.57.1",
"unist-util-visit": "^5.1.0",
"vite": "^8.3.1"
},
"type": "module"
}

Release Screenshots (`docs/release-screenshots.md`) Copy Section

Release screenshots

Recipe for turning the and markers in a GitHub release body into 4x PNGs. It was first run for v0.113.0. Run it as part of the post-release checklist.

Each marker follows a fenced svelte snippet. The goal is for the image to be what that snippet renders, so every snippet is compiled verbatim, bundled with the repo's own src/ and css/all.css, and captured in your installed Chrome. It is a Bun script with no dependencies beyond what the repo already has: no Playwright, no Vite, and nothing written into e2e/. All 15 v0.113.0 shots take about 3.5 seconds cold and well under a second when cached.

This is for running locally. It needs Chrome (or Chromium) installed, and Bun 1.4 or newer for Bun.WebView.

Prerequisites Copy Chapter

• css/all.css exists. It is gitignored and built by bun setup; rebuild it with bun run build:css if your checkout is stale.
• Chrome is installed. Bun finds it automatically; set BUN_CHROME_PATH to use another binary.
• gh is authenticated, if you pass a tag. (A saved Markdown file works without it.)

Steps Copy Chapter

1. Add a recipe for each new marker in scripts/lib/release-screenshot-recipes.ts (see Recipes). A snippet with no recipe is captured as mounted at 420px wide, which is right for static components.

2. Run it. Pass the release tag and the script fetches the notes with gh, or pass a saved Markdown file.

   sh Copy

   bun run release:screenshots vX.Y.Z                 # all
   bun run release:screenshots vX.Y.Z meter box       # some
   bun run release:screenshots notes.md --scale 2 --out /tmp/shots --jobs 2

   Output goes to the gitignored release-screenshots/<name>.png. --jobs sets how many Chrome views capture at once (default 4, or fewer on a smaller machine). Unchanged shots are reused from a cache (see Caching); --no-cache forces a fresh render. A SKIP line means no svelte fence precedes that marker. Keep the markers in the body while drafting; strip them from the published notes when you replace them with images.

3. Check the output. Compare each image against the marker's description, not just "it rendered". Previews of 4x images can exceed viewer size limits; downscale a copy to look, never the original: sips -Z 900 in.png --out /tmp/in.png.

4. Attach the images by dragging the PNGs into the GitHub release editor, then delete the marker comments. Do not commit them.

How it works Copy Chapter

1. extractSnippets pairs each marker with its preceding svelte fence. The fences are written to node_modules/.cache/release-screenshots/<name>.svelte, under the repo so svelte resolves. GitHub returns CRLF line endings; they are normalized first (every fence regex fails otherwise).
2. One Bun.build bundles all snippets as lazy modules chosen by ?s=<name>. A small plugin compiles .svelte files with svelte/compiler and aliases carbon-components-svelte to src/ and its css/ path to css/.
3. Bun.serve serves the bundle from memory on a free port.
4. Chrome and its views start while the bundle builds. Each view (--jobs of them, in one Chrome) pulls shot names off a shared queue, so shots run side by side. A single view allows one CDP call at a time, which is why parallelism comes from views, not from overlapping calls on one. For each shot, a view sets the viewport and deviceScaleFactor through Emulation.setDeviceMetricsOverride, loads the page, waits for fonts and running animations, runs the recipe, then crops Page.captureScreenshot to the #app box.

The browser is always spawned fresh (url: false). Without that, Bun attaches to a Chrome you already have open with remote debugging, and macOS prompts you to allow it.

Caching Copy Chapter

Each shot is cached under node_modules/.cache/release-screenshots/png, keyed on a hash of its snippet, recipe (options and act source), --scale, the library (src/ and css/all.css), and the capture scripts themselves. Edit one recipe and only that shot re-renders. If every shot is cached, Chrome never starts (about 0.2s). Change anything in src/, rebuild the CSS, or edit the scripts and everything re-renders.

Set volatile: true on a recipe whose output depends on the clock, like relative-time, so it is always re-rendered.

Recipes Copy Chapter

Set per-shot options in recipes:

Helpers for act, from scripts/lib/release-screenshots.ts:

Patterns that came up:

Gotchas Copy Chapter

• 4x, PNG, no downscaling. deviceScaleFactor: 4 renders text and edges natively at 4x; it is not an upscale. The files are small (7 to 90 KB) because the content is flat color and text.
• WebView has no element screenshot or scale option. release-screenshots.ts does both over CDP. Round the clip height up (Math.ceil), or Chrome crops a CSS pixel and the image no longer matches an element-screenshot render.
• cdp() needs a session. navigate("about:blank") once before the first cdp call. Each view also allows one cdp or evaluate call in flight, so do not Promise.all them.
• Wait on animations, not timers. settle awaits document.getAnimations(), so menus and calendars are captured after their open animation, with no fixed sleeps.
• Focus rings and hover. A click leaves the clicked element focused, and the mouse stays over it. Call quiet before capture unless the marker asks for focus. Menus are the exception: keep the focus ring on the first item, which is what the component does when opened.
• Native title tooltips are not rendered headlessly. RelativeTime uses title. Draw an equivalent element from the real title value (see the recipe) and say in the PR that it is simulated.
• Capped menus. MultiSelect's menu stops at about 5.5 rows, so a marker that names every group header needs max-height: none on .bx--list-box--expanded .bx--list-box__menu. This changes the default rendering. Disclose it.
• Element screenshots clip popups. Reserve space with min-height on #app; the clip is the #app box.
• Do not change the markup to look better. Layout-only CSS on #app (width, flex row) is fine. Anything that edits the snippet or the component defeats the point; flag every deviation when you hand the images over.
• Svelte 5 compiles these snippets in legacy mode, so let:, slot=, <svelte:fragment slot>, and export let all work as written in release notes.
• Use a fixed viewport width (width + 64) so wrapping is reproducible. GridOverlay is pointer-events: none and sized to the viewport, so capture it at a real breakpoint width (1056 is lg).
• Timestamps differ between runs. RelativeTime's tooltip shows the current time minus five minutes. That is the only expected diff when re-running a release.

Tsconfig.Json (`docs/tsconfig.json`) Copy Section

{
"extends": "../tsconfig.json",
"compilerOptions": {
"allowImportingTsExtensions": true,
"paths": {
"carbon-components-svelte": ["../src"],
"carbon-components-svelte/tokens": ["../src/tokens/index.js"],
"carbon-components-svelte/": ["../"],
"": ["./"]
}
},
"include": ["src//*", "scripts//", ".ts"]
}

Public Robots (`docs/public/robots.txt`) Copy Section

User-agent: *
Allow: /

Sitemap: https://svelte.carbondesignsystem.com/sitemap.xml

--- METRICS ---

• Files Extracted: 7
• Estimated Token Budget: ~13702 tokens
• Canonical Reference: https://codewiki.google/github.com/carbon-design-system/carbon-components-svelte