Nondeterministic Postrequisite Metaprotocol

    carbon-components-svelte
    TypeScript icon, indicating that this package has built-in type declarations

    0.42.0 • Public • Published

    carbon-components-svelte

    NPM GitHub npm downloads to date Build

    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:

    Documentation

    Deploys by Vercel

    The documentation website contains live demos and examples.

    Other forms of documentation are auto-generated:

    Installation

    Install carbon-components-svelte as a development dependency.

    Yarn

    yarn add -D carbon-components-svelte

    NPM

    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.

    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.

    Pre-compiled CSS StyleSheets

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

    • white.css: Default Carbon theme (light)
    • g10.css: Gray 10 theme (light)
    • g80.css: Gray 80 theme (dark)
    • 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.

    The compiled CSS is generated from the following .scss files:

    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" | "g80" | "g90" | "g100"} */
      let theme = "white";
    
      $: document.documentElement.setAttribute("theme", theme);
    </script>
    
    <button on:click="{() => (theme = 'g90')}">Update theme</button>

    Preprocessors

    optimizeCarbonImports

    optimizeCarbonImports is a Svelte preprocessor that optimizes base imports inside the script block of a Svelte file from the following libraries:

    • carbon-components-svelte
    • carbon-icons-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

    import { Button, Header } from "carbon-components-svelte";
    import { Notification20 } from "carbon-icons-svelte";
    import { Airplane } from "carbon-pictograms-svelte";

    After

    import Button from "carbon-components-svelte/Button/Button.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

    // svelte.config.js
    const {
      optimizeCarbonImports,
    } = require("carbon-components-svelte/preprocess");
    
    module.exports = {
      preprocess: [optimizeCarbonImports()],
    };

    svelte-loader

    // 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()],
              },
            },
          },
        ],
      },
    };

    TypeScript support

    TypeScript definitions are generated by sveld.

    Contributing

    Refer to the Contributing guidelines.

    Changelog

    License

    Apache 2.0

    Install

    npm i carbon-components-svelte

    DownloadsWeekly Downloads

    15,092

    Version

    0.42.0

    License

    Apache-2.0

    Unpacked Size

    6.53 MB

    Total Files

    594

    Last publish

    Collaborators

    • avatar