A Carbon Design System variant that's as easy to use as native HTML elements, with no framework tax, no framework silo.

Carbon is an open-source design system built by IBM. With the IBM Design Language as its foundation, the system consists of working code, design tools and resources, human interface guidelines, and a vibrant community of contributors.

carbon-web-components

carbon-web-components

The effort stems from https://github.com/carbon-design-system/issue-tracking/issues/121. If you are interested in this project, adding 👍 to the description of that GH issue, or even contributing, will be greatly appreciated!

• Getting started
  • Basic usage
  • Angular
  • React
  • Vue
  • Other usage guides
• Getting started with development
• Running React/Angular/Vue Storybook demo
• List of available components
• Browser support
• Coding conventions
• Creating build
• Running unit test
• Running build integration test

Getting started

To install

carbon-web-components

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:

The first thing you need is setting up a module bundler to resolve ECMAScript

import

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

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

Once you do that, you can use our components in the same manner as native HTML tags, like:

  Option 1
  Option 2
  Option 3
  Option 4
  Option 5

If you just want to try our components for demonstrations, etc., you can use CDNs that support module mapping (e.g. JSPM). With it, you can just import our modules in

<script type="module">
  import 'https://jspm.dev/carbon-web-components/es/components/dropdown/dropdown.js';
  import 'https://jspm.dev/carbon-web-components/es/components/dropdown/dropdown-item.js';
</script>
<style type="text/css">
  #app {
    font-family: 'IBM Plex Sans', 'Helvetica Neue', Arial, sans-serif;
    width: 300px;
    margin: 2rem;
  }

  bx-dropdown:not(:defined),
  bx-dropdown-item:not(:defined) {
    visibility: hidden;
  }
</style>


<div id="app">
  <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>
</div>

Angular

Angular users can use our components in the same manner as native HTML tags, too, once you add

CUSTOM_ELEMENTS_SCHEMA

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppComponent } from './app.component';
@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  declarations: [AppComponent],
  imports: [BrowserModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

The

.d.ts

carbon-web-components

9.0

.d.ts

• Set

  true

  to

  angularCompilerOptions.disableTypeScriptVersionCheck

  in

  tsconfig.json

• In

  polyfills.ts

  , change

  __importDefault

  TypeScript helper as follows:

  window.__importDefault = mod => (mod?.__esModule ? mod : { default: mod })

React

You can use wrapper React components in

carbon-web-components/es/components-react

import React from 'react';
import { render } from 'react-dom';
import BXDropdown from 'carbon-web-components/es/components-react/dropdown/dropdown.js';
import BXDropdownItem from 'carbon-web-components/es/components-react/dropdown/dropdown-item.js';

const App = () => (
  
    Option 1
    Option 2
    Option 3
    Option 4
    Option 5
  
);
render(, document.getElementById('root'));

Note: Using the React wrapper requires an additional dependency,

prop-types

To run the wrapper React components in SSR environment requires Node

12.16.3

Same Node version requirement applies to Next.js:

Vue

Vue users can use our components in the same manner as native HTML tags, without any additional steps!

Other usage guides

• Having components participate in form
• Using custom styles in components
• Using

  carbon-web-components

  with old build toolchain

Getting started with development

1. Fork this repository and clone it

2. yarn install

3. yarn wca && yarn storybook

Running React/Angular/Vue Storybook demo

• React:

  yarn storybook:react

  (Live demo: https://web-components.carbondesignsystem.com/react/index.html)
• Angular:

  yarn storybook:angular

  (Live demo: https://web-components.carbondesignsystem.com/angular/index.html)
• Vue:

  yarn storybook:vue

  (Live demo: https://web-components.carbondesignsystem.com/vue/index.html)

List of available components

View available web components at: https://web-components.carbondesignsystem.com/. You can see usage information in several ways:

1. Going to Docs tab, where it shows the usage and available attributes, properties and custom events.
2. Clicking the KNOBS tab at the bottom and changing values there. Most knobs are shown as something like

   Button kind (kind)

   , where

   kind

   is the attribute name
3. Clicking the ACTION LOGGER tab at the bottom and interacting with the selected component. You may see something like

   bx-modal-closed

   which typically indicates that an event with such event type is fired. You can also expand the twistie to see the details of the event

Browser support

• Latest Chrome/Safari/FF ESR
• IE/Edge support is bast-effort basis
  • Some components may not be supported

To support IE, you need a couple additional setups:

• Toolstack to re-transpile our code to ES5 (e.g. by specifying IE11 in

  @babel/preset-env

  configuration)
• Polyfills, listed here

Here's an example code that shows such setup:

Coding conventions

Can be found at here.

Creating build

> yarn clean
> yarn build

You'll see the build artifacts in

/path/to/carbon-web-components/es

Running unit test

You can run unit test by:

> gulp test:unit

You can run specific test spec by:

> gulp test:unit -s tests/spec/dropdown_spec.ts

You can choose a browser (instead of Headless Chrome) by:

> gulp test:unit -b Firefox

You can keep the browser after the test (and re-run the test when files change) by:

> gulp test:unit -b Chrome -k

You can prevent code coverate instrumentation code from being generated by:

> gulp test:unit -d

You can update snapshots by:

> gulp test:unit --update-snapshot

Above options can be used together. This is useful to debug your code as you test:

> gulp test:unit -s tests/spec/dropdown_spec.ts -b Chrome -d -k

Running build integration test

You can run build integration test by:

> yarn test:integration:build

You can run a specific set of UI test steps (e.g. running

tests/integration/build/form-angular_steps.js

> yarn test:integration:build form-angular_steps

By default Chrome runs in headless mode. You can show Chrome UI by:

> CI=false yarn test:integration:build

Running UI integration test

You can run UI integration test by:

> yarn test:integration:ui

You can run a specific set of UI test steps (e.g. running

tests/integration/ui/dropdown_steps.js

> yarn test:integration:ui dropdown_steps

By default Chrome runs in headless mode. You can show Chrome UI by:

> CI=false yarn test:integration:ui