Skip to main contentCarbon Design System


The library provides front-end developers and engineers a collection of reusable web components to build websites and user interfaces. Adopting the library enables developers to use consistent markup, styles, and behavior in prototype and production work.

This library uses Custom Elements v1 and Shadow DOM v1 specs.


Getting started

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

npm install -S carbon-web-components carbon-components lit-html lit-element

If you prefer Yarn, use the following command instead:

yarn add carbon-web-components carbon-components lit-html lit-element

Basic usage

Our example at CodeSandbox shows the most basic usage:

Edit carbon-web-components

The first thing you need to do is set up a module bundler to resolve ECMAScript imports. The above example uses Webpack but you can use other bundlers like Rollup too.

Once you set up a module bundler, you can start importing our component modules, for example:

import 'carbon-web-components/es/components/dropdown/dropdown.js';
import 'carbon-web-components/es/components/dropdown/dropdown-item.js';

Once you’ve imported the component modules, you can use our components in the same manner as native HTML tags, for example:

<bx-dropdown trigger-content="Select an item">
<bx-dropdown-item value="all">Option 1</bx-dropdown-item>
<bx-dropdown-item value="cloudFoundry">Option 2</bx-dropdown-item>
<bx-dropdown-item value="staging">Option 3</bx-dropdown-item>
<bx-dropdown-item value="dea">Option 4</bx-dropdown-item>
<bx-dropdown-item value="router">Option 5</bx-dropdown-item>

If you just want to try our components for demonstrations and so on, you can use CDNs that support module mapping (for example, JSPM). With CDNs, you can import just our modules in <script type="module">:

<!DOCTYPE html>
<script type="module">
import '';
import '';
<style type="text/css">
#app {

List of available components

View available web components here. Usage information is available in the notes provided with each story.

JavaScript framework integration

In addition to the available web component versions of Carbon components, this library also supports usage with JavaScript frameworks like Angular, React, and Vue if the desire is to use instead of the pure framework versions of Carbon components. Specifically for React, this library comes with a wrapper implementation around the Carbon Web Components for more seamless integration with your React application.

This is achievable since web components is the modern browser standard, and works well with other front-end frameworks that exist in the application. In turn, this also comes with the benefits of encapsulation within the Shadow DOM:


If you experience any issues while getting set up with Carbon Web Components, please head over to the GitHub repo for more guidelines and support. Please create an issue if your issue does not already exist.