mirror of
https://github.com/carbon-design-system/carbon-components-svelte.git
synced 2025-09-15 18:31:06 +00:00
4dabb827ee
**carbon-components-svelte has unstable styles and interactions during this pre-release phase. See #1872 for details.**
Breaking changes
- Overall, this is a major style change the will impact the appearance and features of many components. Use caution when upgrading and test your applications.
Components
- Button has new prop values for size and kind
- Theme follows v11 conventions: g80 theme isn't supported, toggled themes adjust data-carbon-theme attribute in <html> tag (for now, tokens use bx prefix, but that may change)
- Tabs has a contained prop instead of type, and a new mobile appearance (scrolling tabs)
- ContentSwitcher size prop no longer supports size="xl"; md is the new default
- MultiSelect no longer supports xl size
- OverflowMenu no longer supports xl size
- Search no longer supports xl size
- TreeView no longer supports compact size
- UIShell has a new light theme
CSS
- Several class names have been changed due to the v11 overhaul. If you're targeting or overriding component classes, be sure to test your code
- Many tokens and CSS variables have been renamed. Details: https://carbondesignsystem.com/migrating/guide/develop
- Themes are applied to the <html> element as data-carbon-theme="g10" instead of theme="g10"
- The g80 theme no longer exists
General
- Codebase uses npm instead of yarn
--- Commit notes
* chore: depend on @carbon/styles instead of carbon-components
See upgrade guide here: https://carbondesignsystem.com/migrating/guide/develop
* chore: use v11 styles for docs
* chore: stick to `bx` instead of `cds` class prefix
* chore: migrate layout spacing to v11
See [@carbon/layout](https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#carbonlayout) migration guide:
$layout-01 Removed, use $spacing-05 instead
$layout-02 Removed, use $spacing-06 instead
$layout-03 Removed, use $spacing-07 instead
$layout-04 Removed, use $spacing-09 instead
$layout-05 Removed, use $spacing-10 instead
$layout-06 Removed, use $spacing-12 instead
$layout-07 Removed, use $spacing-13 instead
* chore: migrate type tokens to v11
See https://github.com/carbon-design-system/carbon/blob/main/docs/migration/v11.md#type-tokens
* chore: keep flex-grid instead of css grid for the moment
Upgrading to css-grid should be separate.
* chore: v11 Tabs
In v11 [Tabs](https://carbondesignsystem.com/migrating/guide/design/#tabs-breaking) received some additional modifiers. In this commit we only want to make sure that the Svelte v10 tabs still work using v11 styles. This probably needs additional testing.
* chore: use @ibm/plex fonts
* chore: v11 Button
* dependency: @carbon/styles update
* chore: v11 ComboBox
Size `xl` changed to `lg`. For better compatibility with existing codebases size `xl` is still supported.
* chore: v11 ContentSwitcher
For better compatibility with existing code bases size `xl` is still supported.
* chore: remove legacy v10 css files
Note that further work is needed here in order to make theming work again.
Also documentation needs updating.
* chore: v11 DatePicker
For better compatibility with existing codebases size xl is still supported.
* chore: v11 Dropdown
For better compatibility with existing codebases size xl is still supported.
* chore: v11 ExpandableTile
Note that state labels `tileCollapsedLabel` and `tileExpandedLabel` are no longer supported.
* chore: v11 FileUploader
For better compatibility with existing codebases sizes `field` and `small` are still supported. Note that flagship implementation does the same thing.
* chore: v11 Toggle
This removes legacy `ToggleSkeleton`.
* chore: v11 MultiSelect
Size `xl` changed to `lg`.
* chore: v11 NumberInput
For better compatibility with existing codebases size `xl` is still supported.
* chore: v11 OverflowMenu
Size `xl` changed to `lg`. For better compatibility with existing codebases size `xl` is still supported.
* chore: v11 PasswordInput
Size `xl` changed to `lg`. For better compatibility with existing codebases size `xl` is still supported.
* chore: v11 Search
* chore: v11 Select
Size `xl` changed to `lg`. For better compatibility with existing codebases size `xl` is still supported.
* chore: v11 AspectRatio
The `bx--aspect-ratio--object` class is gone and needs to be replaced manually.
* chore: v11 TextArea
`cols` no longer has a defaults to 50 but remains at 100% width by default.
* chore: v11 TextInput
Size `xl` changed to `lg`. For better compatibility with existing codebases size `xl` is still supported.
* chore: v11 TimePicker
Size `xl` changed to `lg`. For better compatibility with existing codebases size `xl` is still supported.
* chore: v11 TreeView
Size `compact` changed to `xs`. For better compatibility with existing codebases size `compact` is still supported.
* chore: remove Truncate since it does not exist in Carbon v11
* chore: v11 UIShell
* chore: v11 Accordion
Size `xl` changed to `lg`. For better compatibility with existing codebases size `xl` is still supported.
* tmp: v11 PopoverContent
* Revert "chore: remove Truncate since it does not exist in Carbon v11"
This reverts commit 5833536199.
* chore: use truncate mixins
* docs: add truncate mixins
* chore: use `cds` class prefix in v11 styles
* build: switch to npm
* chore: set up all component styles, fonts, and themes
- Adapt documentation to new styles
* chore: add individual theme css
* feat: migrate Theme component to v11
- remove g80 theme option everywhere
- utilize new `data-carbon-theme` attribute when applying theme
- use cds instead of bx in places
* chore: use bx css prefixes for now
* chore: resolve peerDependencies
- Leaving out latest prettier for now
- Ignoring Sveld warnings for now
* chore: fix type errors and tests
---------
Co-authored-by: Gregor Wassmann <gregor.wassmann@gmail.com>
308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
# carbon-components-svelte
|
|
|
|
[![NPM][npm]][npm-url]
|
|
|
|
|
|
<a href="https://discord.gg/J7JEUEkTRX">
|
|
<img src="https://img.shields.io/discord/689212587170201628?color=5865F2&style=for-the-badge" alt="Chat with us on Discord">
|
|
</a>
|
|
|
|
Carbon Components Svelte is a [Svelte](https://github.com/sveltejs/svelte) component library that implements the [Carbon Design System](https://github.com/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:
|
|
|
|
- **[Carbon Icons Svelte](https://github.com/carbon-design-system/carbon-icons-svelte)**: 2,200+ Carbon icons as Svelte components
|
|
- **[Carbon Pictograms Svelte](https://github.com/carbon-design-system/carbon-pictograms-svelte)**: 1,100+ Carbon pictograms as Svelte components
|
|
- **[Carbon Charts Svelte](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte)**: 20+ charts, powered by d3
|
|
- **[Carbon Preprocess Svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte)**: Collection of Svelte preprocessors for Carbon
|
|
|
|
## [Documentation](https://svelte.carbondesignsystem.com)
|
|
|
|
Other forms of documentation are auto-generated:
|
|
|
|
- **[TypeScript definitions](types)**: Component TypeScript definitions
|
|
- **[Component Index](COMPONENT_INDEX.md)**: Component API in Markdown format
|
|
- **[Component API](docs/src/COMPONENT_API.json)**: Component API in JSON format
|
|
|
|
## Installation
|
|
|
|
Install `carbon-components-svelte` as a development dependency.
|
|
|
|
```sh
|
|
# Yarn
|
|
yarn add -D carbon-components-svelte
|
|
|
|
# npm
|
|
npm i -D carbon-components-svelte
|
|
|
|
# pnpm
|
|
pnpm i -D carbon-components-svelte
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Styling
|
|
|
|
Before importing components, you will need to first apply Carbon component styles. The Carbon Design System supports four themes (2 light, 2 dark).
|
|
|
|
- **white.css**: Default Carbon theme (light)
|
|
- **g10.css**: Gray 10 theme (light)
|
|
- **g90.css**: Gray 90 theme (dark)
|
|
- **g100.css**: Gray 100 theme (dark)
|
|
- **all.css**: All themes (White, Gray 10, Gray 90, Gray 100) using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
|
|
|
|
Each StyleSheet is [generated](scripts/build-css.js) from the flagship [carbon-components](https://github.com/carbon-design-system/carbon/tree/main/packages/carbon-components) library.
|
|
|
|
The compiled CSS is generated from the following `.scss` files:
|
|
|
|
- [css/white.scss](css/white.scss)
|
|
- [css/g10.scss](css/g10.scss)
|
|
- [css/g90.scss](css/g90.scss)
|
|
- [css/g100.scss](css/g100.scss)
|
|
- [css/all.scss](css/all.scss)
|
|
|
|
#### CSS StyleSheet
|
|
|
|
```js
|
|
// White theme
|
|
import "carbon-components-svelte/css/white.css";
|
|
|
|
// Gray 10 theme
|
|
import "carbon-components-svelte/css/g10.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";
|
|
```
|
|
|
|
#### CDN
|
|
|
|
An alternative to loading styles is to link an external StyleSheet from a Content Delivery Network (CDN) like [unpkg.com](https://unpkg.com/).
|
|
|
|
This is best suited for rapid prototyping.
|
|
|
|
##### HTML
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<link
|
|
rel="stylesheet"
|
|
href="https://unpkg.com/carbon-components-svelte/css/white.css"
|
|
/>
|
|
</head>
|
|
</html>
|
|
```
|
|
|
|
##### `svelte:head`
|
|
|
|
```html
|
|
<svelte:head>
|
|
<link
|
|
rel="stylesheet"
|
|
href="https://unpkg.com/carbon-components-svelte/css/white.css"
|
|
/>
|
|
</svelte:head>
|
|
```
|
|
|
|
### SCSS
|
|
|
|
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](https://github.com/carbon-design-system/carbon/blob/v10/docs/guides/sass.md) for documentation.
|
|
|
|
### Dynamic theming
|
|
|
|
Use the "all.css" StyleSheet for dynamic, client-side theming.
|
|
|
|
```js
|
|
import "carbon-components-svelte/css/all.css";
|
|
```
|
|
|
|
Update the theme by setting the `theme` attribute on the `html` element. The default `theme` is `"white"`.
|
|
|
|
```html
|
|
<!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.
|
|
|
|
```html
|
|
<script>
|
|
let theme = "white"; // "white" | "g10" | "g90" | "g100"
|
|
|
|
$: document.documentElement.setAttribute("theme", theme);
|
|
</script>
|
|
```
|
|
|
|
### Importing components
|
|
|
|
Import components from `carbon-components-svelte` in the `script` tag of your Svelte file. Visit the [documentation site](https://svelte.carbondesignsystem.com) for examples.
|
|
|
|
```html
|
|
<!-- 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](COMPONENT_INDEX.md) for component API documentation.**
|
|
|
|
## Preprocessors & Plugins
|
|
|
|
[carbon-preprocess-svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte) is a collection of Svelte preprocessors for Carbon.
|
|
|
|
> [!INFO]
|
|
> Using `carbon-preprocess-svelte` is optional and not a prerequisite to using this library. It's designed for better developer experience in addition to CSS build performance.
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
- [carbon-components-svelte](https://github.com/carbon-design-system/carbon-components-svelte)
|
|
- [carbon-icons-svelte](https://github.com/carbon-design-system/carbon-icons-svelte)
|
|
- [carbon-pictograms-svelte](https://github.com/carbon-design-system/carbon-pictograms-svelte)
|
|
|
|
**Before & After**
|
|
|
|
```diff
|
|
- 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";
|
|
```
|
|
|
|
#### Usage
|
|
|
|
See [examples](examples) for full configurations.
|
|
|
|
```js
|
|
// 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`.
|
|
|
|
```diff
|
|
// 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](https://vitejs.dev/guide/api-plugin) extends the Rollup plugin API).
|
|
|
|
`carbon-components-svelte@0.85.0` or greater is required.
|
|
|
|
```diff
|
|
$ 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.
|
|
|
|
#### Usage
|
|
|
|
See [examples](examples) for full configurations.
|
|
|
|
```js
|
|
// 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()],
|
|
});
|
|
```
|
|
|
|
## Examples
|
|
|
|
- [examples/rollup](examples/rollup/)
|
|
- [examples/sveltekit](examples/sveltekit/)
|
|
- [examples/vite](examples/vite/)
|
|
- [examples/webpack](examples/webpack/)
|
|
|
|
## TypeScript support
|
|
|
|
[TypeScript definitions](types) are generated by [sveld](https://github.com/carbon-design-system/sveld).
|
|
|
|
## Contributing
|
|
|
|
Refer to the [Contributing guidelines](CONTRIBUTING.md).
|
|
|
|
## [Changelog](CHANGELOG.md)
|
|
|
|
## License
|
|
|
|
[Apache 2.0](LICENSE)
|
|
|
|
[npm]: https://img.shields.io/npm/v/carbon-components-svelte.svg?color=262626&style=for-the-badge
|
|
[npm-url]: https://npmjs.com/package/carbon-components-svelte
|
|
|
|
## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry
|
|
|
|
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](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).
|