Carbon Components Svelte is a Svelte component library that implements the Carbon Design System, an open source design system by IBM.
Design systems facilitate design and development through reuse, consistency, and extensibility.
The Carbon Svelte portfolio also includes:
Other forms of documentation are auto-generated:
Install carbon-components-svelte
as a development dependency.
# Yarn
yarn add -D carbon-components-svelte
# npm
npm i -D carbon-components-svelte
# pnpm
pnpm i -D carbon-components-svelte
Before importing components, you will need to first apply Carbon component styles. The Carbon Design System supports five themes (2 light, 3 dark).
Each StyleSheet is generated from the flagship carbon-components library.
The compiled CSS is generated from the following .scss
files:
// 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";
The most performant method to load styles is to import SCSS directly from carbon-components. Although it requires more set up, you can reduce the size of the bundle CSS by importing individual component styles instead of a pre-compiled CSS StyleSheet.
Refer to the official Carbon guide on SASS for documentation.
Use the "all.css" StyleSheet for dynamic, client-side theming.
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>
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>
Import components from carbon-components-svelte
in the script
tag of your Svelte file. Visit the documentation site for examples.
<!-- App.svelte -->
<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 COMPONENT_INDEX.md for component API documentation.
carbon-preprocess-svelte is a collection of Svelte preprocessors for Carbon.
[!NOTE] Using
carbon-preprocess-svelte
is optional and not a prerequisite for this library.
# Yarn
yarn add -D carbon-preprocess-svelte
# npm
npm i -D carbon-preprocess-svelte
# pnpm
pnpm i -D carbon-preprocess-svelte
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:
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";
See examples for full configurations.
// svelte.config.js
import { optimizeImports } from "carbon-preprocess-svelte";
export default {
preprocess: [optimizeImports()],
};
Any other preprocessors that transpile code in the script
block should be invoked before optimizeImports
.
For example, vitePreprocess
should precede optimizeImports
.
// svelte.config.js
+ import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeImports } from "carbon-preprocess-svelte";
export default {
preprocess: [
+ vitePreprocess(),
optimizeImports()
],
};
optimizeCss
optimizeCss
is a Vite plugin that removes unused Carbon styles at build time. The plugin is compatible with Rollup (Vite extends the Rollup plugin API).
[email protected]
or greater is required.
$ vite build
Optimized index-CU4gbKFa.css
- Before: 606.26 kB
+ After: 53.22 kB (-91.22%)
dist/index.html 0.34 kB │ gzip: 0.24 kB
dist/assets/index-CU4gbKFa.css 53.22 kB │ gzip: 6.91 kB
dist/assets/index-Ceijs3eO.js 53.65 kB │ gzip: 15.88 kB
[!NOTE] This is a plugin and not a Svelte preprocessor. It should be added to the list of
vite.plugins
. For Vite set-ups, this plugin is only run when building the app. For Rollup and Webpack, you should conditionally apply the plugin to only execute when building for production.
See examples for full configurations.
// vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { optimizeCss } from "carbon-preprocess-svelte";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [sveltekit(), optimizeCss()],
});
TypeScript definitions are generated by sveld.
Refer to the Contributing guidelines.
This package uses IBM Telemetry to collect anonymous 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.