carbon-components

carbon-components

Styles for the Carbon Design System

Getting started

To install carbon-components in your project, you will need to run the following command using npm:

npm install -S carbon-components

If you prefer Yarn, use the following command instead:

yarn add carbon-components

This package requires Dart Sass in order to compile. It uses Sass modules to organize the codebase and provide exports to use.

If you're new to Sass, or are wondering how to configure Sass for your project, we recommend checking out the following resources and links:

• Sass Basics
• Webpack with Sass
• Next.js with Sass
• Create React App with Sass
• Parcel with Sass
• Vite with Sass
• Snowpack with Sass

Once you get Sass up and running in your project, make sure to configure Sass to include node_modules in its includePaths option. For more information, checkout the configuration section in our Sass docs.

Usage

You can bring in all the styles for the Carbon Design System by including carbon-components in your Sass files. For example:

@use 'carbon-components';

If you only would like to bring in specific components from Carbon, you can import them in a similar way:

@use 'carbon-components/scss/reset';
@use 'carbon-components/scss/components/accordion';
@use 'carbon-components/scss/components/button';
@use 'carbon-components/scss/components/checkbox';

There are various helpers that you can include from Carbon, as well, such as a CSS reset, grid, breakpoint helpers, and more. You can include these similar to how you bring in components:

// Bring in the CSS Reset
@use 'carbon-components/scss/reset';

// Bring in the CSS Grid
@use 'carbon-components/scss/grid';

To learn more about the various helpers that carbon-components provides, checkout the overview of the files available to use in our Sass docs.

Theming

You can change the default theme of Carbon by doing the following:

@use 'carbon-components/scss/themes';
@use 'carbon-components/scss/theme' with (
  $theme: themes.$g100
);

This example uses a built-in theme from Carbon provided by the scss/themes entrypoint. You can also use a custom theme, or add your own custom tokens to extend the theme.

// Configure with a custom theme
@use 'carbon-components/scss/theme' with (
  $theme: (
    background: #e2e2e2,
    text-primary: #ffffff,
  )
);

// Extend the g100 theme with your own tokens
@use 'carbon-components/scss/themes';
@use 'carbon-components/scss/theme' with (
  $fallback: themes.$g100,
  $theme: (
    custom-token-01: #000000,
  )
);

Design tokens

You can access the design tokens defined by the Carbon Design System through the carbon-components/scss/theme entrypoint. This file will allow you to refer to tokens using Sass Variables as well as get the current value for any token in the current theme. For example:

@use 'carbon-components/scss/theme';

body {
  background: theme.$background;
}

For a full list of tokens available for you to use, check out our theming documentation.

📖 API Documentation

If you're looking for carbon-components API documentation, check out:

• Sass

🙌 Contributing

We're always looking for contributors to help us fix bugs, build new features, or help us improve the project documentation. If you're interested, definitely check out our Contributing Guide! 👀

📝 License

Licensed under the Apache 2.0 License.

IBM Telemetry

This package uses IBM Telemetry to collect metrics data. 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.