mirror of https://github.com/carbon-design-system/carbon-components-svelte.git synced 2025-09-14 18:01:06 +00:00

Eric Liu f2a3f8d2e1

Alignment with Carbon version 10.27 (#495 )

* chore(deps-dev): bump devDependencies

* docs: update number of available carbon icons

* feat(notification): distinguish dispatched close event between click/timeout

* fix(notification): prevent class from being overriden by $$restProps

* docs(notification): improve example body copy

* fix(notification): remove notificationType prop

* refactor(notification): resolve svelte file in imports

* fix(notification): prevent class from being overridden by $$restProps

* feat(notification): update TS signature for dispatched close event

* docs: update contributing

* fix(loading): adjust spinner styles

* feat(tag): support custom icon variant

* feat(tile): add optional expand/collapse icon labels to ExpandableTile

* feat(code-snippet): support disabled state for single and multi-line types

* fix(code-snippet): remove impossible class directive

* fix(code-snippet): showMoreLess button size should be "field", not "small"

* fix(password-input): disable visibility button

- set default values for tooltipAlignment, tooltipPosition

* fix(text-input): add missing warning field wrapper class

* feat(button): infer hasIconOnly using $$slots API

- requires Svelte version >=3.25

* docs(button): add danger tertiary, icon-only example

* feat(button): set default values for tooltip alignment, position

* docs: document dynamic theming

* fix(modal): correctly set class props #482

* fix(form): forward submit event in FluidForm #487

* feat(dropdown): support warning state

* feat(multi-select): support warning state

* fix(multi-select): prevent dropdown from opening if disabled

* feat(number-input): support warning state

* chore(deps-dev): upgrade devDependencies

* docs:  bump @carbon/themes, carbon-components

* refactor(data-table): co-locate DataTableSkeleton with DataTable

* docs: update number of pictograms

* fix(password-input): add missing "bx--btn" class to visibility toggle

* docs: increase z-index for component preview

2021-01-27 13:29:20 -08:00

6 KiB

Raw Blame History

carbon-components-svelte

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:

Carbon Icons Svelte: 6000+ Carbon icons as Svelte components
Carbon Pictograms Svelte: 700+ Carbon pictograms as Svelte components
Carbon Charts Svelte: 16 chart types, powered by d3

Documentation

The documentation website contains live demos and examples.

Other forms of documentation are auto-generated:

TypeScript definitions: Component TypeScript definitions
Component Index: Markdown file documenting component props, slots, and events
Component API: Component API metadata in JSON format

Getting started

Install carbon-components-svelte as a development dependency.

yarn add -D carbon-components-svelte
# OR
npm i -D carbon-components-svelte

Usage

The quickest way to get started is to customize a template from the examples folder.

Example set-ups demonstrate usage with popular application bundlers and frameworks. They include a mix of client-side rendering (CSR) and server-side rendering (SSR) approaches.

examples/rollup: SPA bundled using Rollup
examples/rollup-typescript: SPA bundled using Rollup with TypeScript support
examples/routify: SPA + static export using Routify
examples/sapper: SSR + static export using Sapper
examples/svite: SPA developed with Svite, bundled with Rollup
examples/webpack: SPA bundled with webpack

Scaffolding

Each example is published in a dedicated branch of the same name.

Use degit to scaffold a new project:

For example, to use the svite template, run the following commands:

npx degit ibm/carbon-components-svelte#svite svelte-app
cd svelte-app
yarn install

Importing components

Import components from carbon-components-svelte in the script tag of your Svelte file.

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

Precompiled CSS StyleSheets

carbon-components-svelte includes precompiled CSS StyleSheets for each Carbon theme:

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

Each StyleSheet is generated from the flagship carbon-components library..

Usage

`svelte-preprocess`

The easiest way to import a StyleSheet is with svelte-preprocess.

const svelteOptions = {
  preprocess: require("svelte-preprocess")(),
};

<!-- App.svelte -->
<style lang="scss" global>
  /** Gray 10 theme **/
  @import "carbon-components-svelte/css/g10";
</style>

JavaScript import

Importing a CSS file in a JavaScript file will require the appropriate file loader(s).

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

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

Using JavaScript:

<script>
  /** @type {"white" | "g10" | "g90" | "g100"} */
  let theme = "white";

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

<button on:click="{() => theme = 'g90'}">Update theme</button>