Frameworks – Carbon 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.

For support, contact the Carbon Web Components team.

v11 upgrade for Carbon Web Components is coming soon.

Resources

Carbon Web Components

Try web components with CodeSandbox

Getting started

Using CDN

How to install

All components are available via CDN. This means that they can be added to your application without the need of any bundler configuration. Each component is available by the latest tag, or referencing a specific version (starting at version v1.16.0):

<!-- By `latest` tag -->
<script
  type="module"
  src="https://1.www.s81c.com/common/carbon/web-components/tag/latest/accordion.min.js"
></script>

<!-- By specific version -->
<script
  type="module"
Copy to clipboard

These are the list of available components via CDN:

accordion.min.js
breadcrumb.min.js
button.min.js
checkbox.min.js
code-snippet.min.js
combo-box.min.js
content-switcher.min.js
copy-button.min.js
data-table.min.js
date-picker.min.js
dropdown.min.js
file-uploader.min.js
floating-menu.min.js
form.min.js
inline-loading.min.js
input.min.js
link.min.js
list.min.js
loading.min.js
modal.min.js
multi-select.min.js
notification.min.js
number-input.min.js
overflow-menu.min.js
pagination.min.js
progress-indicator.min.js
radio-button.min.js
search.min.js
select.min.js
skeleton-placeholder.min.js
skeleton-text.min.js
skip-to-content.min.js
slider.min.js
structured-list.min.js
tabs.min.js
tag.min.js
textarea.min.js
tile.min.js
toggle.min.js
tooltip.min.js
ui-shell.min.js

To use the right-to-left (RTL) version of the artifacts, change the file extention from .min.js to .rtl.min.js. For example:

<!-- By `latest` tag (RTL) -->
<script
  type="module"
  src="https://1.www.s81c.com/common/carbon/web-components/tag/latest/accordion.rtl.min.js"
></script>

<!-- By specific version (RTL) -->
<script
  type="module"
Copy to clipboard

Basic usage

The CDN artifacts define the custom elements for the browser, so they can be directly used once the script tag has been added to the page. For example:

<!DOCTYPE html>
<html>
  <head>
    <script
      type="module"
      src="https://1.www.s81c.com/common/carbon/web-components/tag/latest/dropdown.min.js"
    ></script>
    <style type="text/css">
      // Suppresses the custom element until it has been defined
Copy to clipboard

Our example at CodeSandbox shows usage with only CDN artifacts:

Using ES imports

How to install

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
Copy to clipboard

If you prefer Yarn, use the following command instead:

yarn add carbon-web-components carbon-components lit-html lit-element
Copy to clipboard

Basic usage

Our example at CodeSandbox shows the most basic usage:

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/index.js';
Copy to clipboard

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>
</bx-dropdown>
Copy to clipboard

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:

Note: The approaches above detail the usage of Carbon Web Components within popular JavaScript frameworks. The APIs are based on how the web components are used, and differ from its pure framework counterparts (Carbon React, Carbon Angular, Carbon Vue).

Troubleshooting

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.

Edit this page on GitHub

Frameworks: React

Frameworks: Angular