# carbon-components-svelte: IBM's Carbon Design System as 90+ Svelte Components

> A Svelte component library that ports the Carbon Design System, with five themes, a typed TypeScript API and an optional preprocessor set for build size. It suits teams already committed to Carbon or Svelte, and it is a poor fit if you need a stable 1.0 API.

**carbon-design-system/carbon-components-svelte** — Svelte implementation of the Carbon Design System

- Repository: https://github.com/carbon-design-system/carbon-components-svelte
- Website: https://svelte.carbondesignsystem.com
- Stars: 2,908 · Forks: 267
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/carbon-design-system-carbon-components-svelte

## The gap carbon-components-svelte fills

Carbon is IBM's open source design system, and its flagship implementation targets React. A Svelte team that wants Carbon's look and behaviour has two bad options otherwise: hand-port components, or wrap the React package and carry a framework runtime into a Svelte app. carbon-components-svelte exists to remove that choice. It is a Svelte component library that implements Carbon, and the README frames the goal plainly: ship accessible, consistent, production-ready interfaces.

The audience is narrow but real. You are building a Svelte or SvelteKit application, someone above you has decided the product should look like Carbon, and you would rather import a Button than reimplement one. The README lists the scope: 90+ components from inputs to data tables, five built-in themes (two light, three dark), a fully typed TypeScript API covering props, events and slots, and a WCAG 2.1 AA accessibility claim. The library also sits in a wider set of Carbon packages for Svelte, covering 2,700+ icons, 1,500+ pictograms, 25+ d3-powered charts, and a preprocessor collection.

That ecosystem is the actual selling point. A design system is not a button; it is a button, an icon set, a chart palette and a theme that agree with each other. If you only needed a button, you would not be reading about Carbon.

## How styles, themes and components fit together

The library is published as ESM. The package.json sets "type": "module", points the svelte and main fields at ./src/index.js, and exposes types at ./src/index.d.ts. Components ship as .svelte source rather than a compiled bundle, which is why the exports map has entries for ./src/*.svelte and ./src/*.js. That matters: your bundler compiles the components, so Svelte version compatibility is decided at build time, not by a prebuilt artifact.

Styling is deliberately separate. The README states that you must apply Carbon component styles before importing components, and those stylesheets are generated from the flagship carbon-components library by a build script (scripts/build-css.ts) from SCSS sources under css/. Six compiled stylesheets are shipped: white.css, g10.css, g80.css, g90.css, g100.css and all.css. The first five are single themes; all.css bundles all five using CSS custom properties.

Dynamic theming follows from that design. With all.css loaded, the active theme is read from a theme attribute on the html element, defaulting to "white". The README shows setting it declaratively in markup and programmatically through document.documentElement.setAttribute("theme", theme). There is also a Theme component for managing it reactively. The trade-off is honest: all.css ships every theme so you can switch at runtime, while a single-theme stylesheet ships less CSS but fixes the theme at build time.

The repository layout supports the claim that this is maintained as a real library rather than a demo: separate test trees for Svelte 3 and Svelte 4 (tests-svelte3/, tests-svelte4/), Playwright end-to-end tests, a bench/ directory, a perf Vite config, and example projects for Rollup, Vite, Webpack and SvelteKit. The last push to the repository was on 2026-09-23, and the most recent release listed is v0.112.0 on 2026-09-11.

## Installing carbon-components-svelte and rendering a first component

Install the package with the package manager you already use. The README lists npm, pnpm, Yarn and Bun commands; the npm form is npm i carbon-components-svelte.

```bash
npm i carbon-components-svelte
```

Before any component renders correctly you need a Carbon stylesheet. Import exactly one theme at your top-level entry point, which the README describes as index.js or src/+layout.svelte. The default light theme is white.css.

```js
import "carbon-components-svelte/css/white.css";
```

If you want runtime theme switching instead, import the combined stylesheet and set the theme attribute on the html element. The default is "white", and valid values are white, g10, g80, g90 and g100.

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

Components are imported from the package root inside a Svelte script tag. The README's example uses Accordion and AccordionItem, where each item takes a title prop and an optional open flag.

```html
<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>
</Accordion>
```

What you should see is a Carbon-styled accordion with the first section expanded. If the component renders but looks unstyled, the stylesheet import is missing or placed below the component import in the entry chain. The README points to the documentation site for per-component API details; the package itself does not document each component's props inline.

## carbon-preprocess-svelte and the cost of barrel imports

The README is explicit that carbon-preprocess-svelte is optional and not a prerequisite, and that it should be installed as a development dependency. It exists because the natural way to import from this library is also the slow way.

A barrel import like import { Button } from "carbon-components-svelte" makes the bundler walk a large index. The optimizeImports preprocessor rewrites those imports to direct source paths at compile time, and the README's before/after diff shows the shape: a named import from the package root becomes a default import from carbon-components-svelte/src/Button/Button.svelte. It does the same for carbon-icons-svelte and carbon-pictograms-svelte. The stated benefit is faster development and production compile times while keeping IDE typeahead and autocompletion intact.

The second tool, optimizeCss, is a Vite plugin that removes unused Carbon styles at build time. The README says it often removes hundreds of kilobytes, and the sentence is truncated at that point, so treat the figure as the README's own estimate rather than a measured number.

```bash
npm i -D carbon-preprocess-svelte
```

My read: if you are shipping a Carbon app of any size, optimizeImports is close to mandatory in practice, because barrel imports of a 90+ component library are exactly the pattern that makes dev-server restarts feel slow. The library authors clearly know this, which is why the preprocessor package exists and why the README links it from the main page. The cost is one more build-time dependency and a preprocessor config to maintain.

## Where carbon-components-svelte is the wrong choice

The version line is the first thing to weigh. The most recent release listed is v0.112.0, published on 2026-09-11, and the two before it are v0.111.1 and v0.111.0. This is a pre-1.0 library. Nothing in the README promises API stability, and a minor version bump in a 0.x line can carry breaking changes. If your organisation requires a stable major version before adopting a component library, this is not that library today.

The second constraint is structural: the package ships Svelte source, not compiled components. That is good for tree-shaking and bad for anyone who wanted a framework-agnostic artifact. You cannot use this from React, Vue or plain HTML without a Svelte build step. If your application is not a Svelte application, the library has nothing to offer you.

Third, Carbon is a specific visual language. It is dense, enterprise-oriented and opinionated about spacing, type scale and colour. If your product's design direction is anything else, adopting this library means fighting it, and a smaller unstyled component set plus your own CSS would be less work. The five themes are Carbon themes, not a general theming system you can repoint at arbitrary brand tokens.

Finally, the README is thin on migration. It documents installation, styling, theming and imports, and it points to the documentation site for component APIs, but it does not document an upgrade path between minor versions, a deprecation policy, or rollback. For a pre-1.0 library, that silence is the risk you are accepting.

## How this differs from React Carbon and from unopinionated Svelte kits

The closest comparison is Carbon's React implementation. Both implement the same design system, and the difference is not visual but structural: the React package is the flagship that the Svelte stylesheets are generated from, via scripts/build-css.ts reading the carbon-components library. So the Svelte port inherits Carbon's CSS and reimplements the component behaviour in Svelte. Practically, that means the Svelte library trails the React one whenever Carbon changes, and that its fidelity depends on how faithfully each component was ported. If your team is on React, use the React package; there is no reason to introduce Svelte to get Carbon.

The other comparison is with general-purpose Svelte component kits, such as Flowbite Svelte. Those give you a broad set of components with a lighter design opinion and let you supply the visual identity. Carbon Svelte does the opposite: it hands you IBM's identity and expects you to accept it. The difference shows up in the theming section. Flowbite-style kits typically expose design tokens you redefine; Carbon Svelte exposes five fixed themes selected by a theme attribute on the html element, with all.css bundling all five. That is a closed set by design.

There is also a middle path the README mentions without recommending: importing SCSS directly from carbon-components. The README calls it the most performant method to load styles, at the cost of more setup, and links to Carbon's own SASS guide. If bundle size is your binding constraint, that route plus optimizeCss is where the savings are, not in swapping component libraries.

## Maintenance, licensing and what upgrades cost

The repository is not archived, and its last push was on 2026-09-23, one day before the date used for this assessment. Releases have landed steadily through 2026, with v0.112.0 on 2026-09-11. The test layout is a useful signal about what the maintainers actually support: tests-svelte3/ and tests-svelte4/ are separate workspaces with their own test and type-check scripts, and the root package.json wires test:svelte3, test:types:svelte3, test:svelte4 and test:types:svelte4. There is also a Playwright end-to-end suite and a perf config. That is more verification infrastructure than most component libraries carry, and it tells you which Svelte majors are in scope.

The upgrade cost is mostly the pre-1.0 version line. Because components ship as source and are compiled by your bundler, a minor release can change a component's internals or its TypeScript types in ways that surface as build errors in your app rather than at install time. Budget for reading CHANGELOG.md before bumping, and for running your own type checks, since the library's own svelte-check runs are not a substitute for checking your usage.

On licensing: the package declares Apache-2.0 in both the repository metadata and package.json, and the repository carries a LICENSE file plus a SECURITY.md and CONTRIBUTING.md. Apache-2.0 is a permissive licence with an explicit patent grant and notice requirements. I am not giving legal advice; if you redistribute the library or modified versions of it, have your own counsel confirm what notices you must carry.

## Conclusion

Adopt carbon-components-svelte if your team has already chosen Svelte and wants Carbon's visual language without rebuilding it, especially if you need IBM's five themes and a typed component API. Do not adopt it if you need a stable 1.0 release line, since the current version is 0.112.0 and the README shows no 1.0 plan, or if you are not using Svelte at all. Before committing, verify that the components you need exist in the docs site, check that your Svelte version is covered by the tests-svelte3 and tests-svelte4 suites in the repository, and confirm which Carbon theme your product requires so you import one stylesheet rather than all.css.

## FAQ

### How do I install carbon-components-svelte?

Install it with your package manager, for example npm i carbon-components-svelte. Then import one Carbon stylesheet at your top-level entry point before importing any components.

### Which themes does carbon-components-svelte support?

Five: white (the default light theme), g10 (light), and g80, g90 and g100 (dark). Each has its own compiled stylesheet, and all.css bundles all five using CSS custom properties for runtime switching.

### How do I switch themes at runtime in carbon-components-svelte?

Import carbon-components-svelte/css/all.css instead of a single theme, then set the theme attribute on the html element to one of white, g10, g80, g90 or g100. The README also mentions a Theme component for managing this reactively.

### What is carbon-preprocess-svelte used for?

It is an optional development dependency. Its optimizeImports preprocessor rewrites barrel imports from Carbon components, icons and pictograms to direct source paths to speed up compile times, and its optimizeCss Vite plugin removes unused Carbon styles at build time.

### Does carbon-components-svelte work with Svelte 3 and Svelte 4?

The repository contains separate test workspaces named tests-svelte3 and tests-svelte4, each with its own test and type-check scripts wired into package.json, which indicates both majors are covered by the project's test setup.

## Sources

- [carbon-design-system/carbon-components-svelte on GitHub](https://github.com/carbon-design-system/carbon-components-svelte)
- [License: Apache-2.0](https://github.com/carbon-design-system/carbon-components-svelte/blob/master/LICENSE)
- [Project website](https://svelte.carbondesignsystem.com)
- [README](https://github.com/carbon-design-system/carbon-components-svelte/blob/master/README.md)
- [Releases](https://github.com/carbon-design-system/carbon-components-svelte/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/carbon-design-system-carbon-components-svelte