mcp/carbon-components-svelte
1
0
Fork 0
mirror of https://github.com/carbon-design-system/carbon-components-svelte.git synced 2025-09-18 11:36:36 +00:00
Code Issues Projects Releases Packages Wiki Activity

chore: update readme docs

Browse source
This commit is contained in:
Eric Y Liu 2021-07-29 15:42:16 -07:00
commit 568b256471
1 changed files with 110 additions and 108 deletions
Download patch file Download diff file Expand all files Collapse all files

218
README.md
View file

@ -46,28 +46,9 @@ npm i -D carbon-components-svelte
## Usage ## Usage
### Importing components ### Styling
Import components from `carbon-components-svelte` in the `script` tag of your Svelte file. Before importing components, you will need to first apply Carbon component styles. The Carbon Design System supports five themes (2 light, 3 dark).
```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.**
### Pre-compiled CSS StyleSheets
`carbon-components-svelte` includes pre-compiled CSS StyleSheets for each Carbon theme:
- **white.css**: Default Carbon theme (light) - **white.css**: Default Carbon theme (light)
- **g10.css**: Gray 10 theme (light) - **g10.css**: Gray 10 theme (light)
@ -87,45 +68,73 @@ The compiled CSS is generated from the following `.scss` files:
- [css/g100.scss](css/g100.scss) - [css/g100.scss](css/g100.scss)
- [css/all.scss](css/all.scss) - [css/all.scss](css/all.scss)
#### Usage #### CSS StyleSheet
##### `svelte-preprocess`
The easiest way to import a StyleSheet is with [svelte-preprocess](https://github.com/sveltejs/svelte-preprocess).
```js ```js
const svelteOptions = { // White theme
preprocess: require("svelte-preprocess")(), 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";
``` ```
#### 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 ```html
<!-- App.svelte --> <!DOCTYPE html>
<style lang="scss" global> <html>
/** Gray 10 theme **/ <head>
@import "carbon-components-svelte/css/g10"; <link
</style> rel="stylesheet"
href="https://unpkg.com/carbon-components-svelte/css/white.css"
/>
</head>
</html>
``` ```
##### JavaScript import ##### `svelte:head`
Importing a CSS file in a JavaScript file will require the appropriate file loader(s). ```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/main/docs/guides/sass.md) for documentation.
### Dynamic theming
Use the "all.css" StyleSheet for dynamic, client-side theming.
```js ```js
import "carbon-components-svelte/css/all.css"; import "carbon-components-svelte/css/all.css";
import App from "./App.svelte";
const app = new App({ target: document.body });
export default app;
``` ```
See [webpack.config.js](examples/webpack/webpack.config.js) in [examples/webpack](examples/webpack).
#### Dynamic theming
Use `carbon-components-svelte/css/all.css` for dynamic, client-side styling.
Update the theme by setting the `theme` attribute on the `html` element. The default `theme` is `"white"`. Update the theme by setting the `theme` attribute on the `html` element. The default `theme` is `"white"`.
```html ```html
@ -137,87 +146,80 @@ Update the theme by setting the `theme` attribute on the `html` element. The def
</html> </html>
``` ```
Using JavaScript: Programmatically switch between each of the five Carbon themes by setting the "theme" attribute on the HTML element.
```svelte ```html
<script> <script>
/** @type {"white" | "g10" | "g80" | "g90" | "g100"} */ let theme = "white"; // "white" | "g10" | "g80" | "g90" | "g100"
let theme = "white";
$: document.documentElement.setAttribute("theme", theme); $: document.documentElement.setAttribute("theme", theme);
</script> </script>
<button on:click="{() => (theme = 'g90')}">Update theme</button>
``` ```
### Importing components
Import components from `carbon-components-svelte` in the `script` tag of your Svelte file. Visit the [documentation site](http://ibm.biz/carbon-svelte) 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 ## Preprocessors
### optimizeCarbonImports [carbon-preprocess-svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte) is a collection of Svelte preprocessors for Carbon.
`optimizeCarbonImports` is a Svelte preprocessor that optimizes base imports inside the `script` block of a Svelte file from the following libraries: **Yarn**
- carbon-components-svelte ```sh
- carbon-icons-svelte yarn add -D carbon-preprocess-svelte
- carbon-pictograms-svelte
The preprocessor rewrites base imports to directly import the source Svelte file. This may lead to faster complile times **during development**.
Example:
**Before**
```js
import { Button, Header } from "carbon-components-svelte";
import { Notification20 } from "carbon-icons-svelte";
import { Airplane } from "carbon-pictograms-svelte";
``` ```
**After** **NPM**
```js ```sh
import Button from "carbon-components-svelte/Button/Button.svelte"; npm i -D carbon-preprocess-svelte
import Header from "carbon-components-svelte/UIShell/GlobalHeader/Header.svelte";
import Notification20 from "carbon-icons-svelte/lib/Notification20/Notification20.svelte";
import Airplane from "carbon-pictograms-svelte/lib/Airplane/Airplane.svelte";
``` ```
#### svelte.config.js ### `optimizeImports`
`optimizeImports` is a script preprocessor that rewrites base imports from Carbon components/icons/pictograms packages to their source Svelte code paths. This can greatly speed up compile times during development while preserving typeahead and autocompletion hinting offered by integrated development environments (IDE) like VSCode.
The preprocessor optimizes imports from the following packages:
- [carbon-components-svelte](https://github.com/IBM/carbon-components-svelte)
- [carbon-icons-svelte](https://github.com/IBM/carbon-icons-svelte)
- [carbon-pictograms-svelte](https://github.com/IBM/carbon-pictograms-svelte)
**Example**
```diff
- import { Button } from "carbon-components-svelte";
- import { Add16 } from "carbon-icons-svelte";
- import { Airplane } from "carbon-pictograms-svelte";
+ import Button from "carbon-components-svelte/Button/Button.svelte";
+ import Add16 from "carbon-icons-svelte/lib/Add16/Add16.svelte";
+ import Airplane from "carbon-pictograms-svelte/lib/Airplane/Airplane.svelte";
```
#### Usage
```js ```js
// svelte.config.js // svelte.config.js
const { import { optimizeImports } from "carbon-preprocess-svelte";
optimizeCarbonImports,
} = require("carbon-components-svelte/preprocess");
module.exports = { export default {
preprocess: [optimizeCarbonImports()], preprocess: [optimizeImports()],
};
```
#### svelte-loader
```js
// webpack.config.js
const {
optimizeCarbonImports,
} = require("carbon-components-svelte/preprocess");
module.exports = {
// ...
module: {
rules: [
{
test: /\.svelte$/,
use: {
loader: "svelte-loader",
options: {
hotReload: true,
preprocess: [optimizeCarbonImports()],
},
},
},
],
},
}; };
``` ```