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-custom-elements`

carbon-custom-elements is a variant of Carbon Design System with Custom Elements v1 and Shadow DOM v1 specs.

Experimental at this moment, with enthusiasm.

The effort stems from carbon-design-system/issue-tracking#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
Iteration plans
Creating build
Running unit test

Getting started

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

npm install -S carbon-custom-elements carbon-components lit-html lit-element classnames lodash.findlast @babel/runtime

If you prefer Yarn, use the following command instead:

yarn add carbon-custom-elements carbon-components lit-html lit-element classnames lodash.findlast @babel/runtime

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 imports. Above example uses Parcel. You can use other bundlers like Rollup/Webpack, too.

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

import 'carbon-custom-elements/es/components/dropdown/dropdown';
import 'carbon-custom-elements/es/components/dropdown/dropdown-item';

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

<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>

Angular

Angular users can use our components in the same manner as native HTML tags, too, once you add CUSTOM_ELEMENTS_SCHEMA schema to your Angular module, like:

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 {}

React

You can use wrapper React components in carbon-custom-elements/es/components-react that allows you to use our components seamlessly from your React code. Here's an example:

import React from 'react';
import { render } from 'react-dom';
import BXDropdown from 'carbon-custom-elements/es/components-react/dropdown/dropdown';
import BXDropdownItem from 'carbon-custom-elements/es/components-react/dropdown/dropdown-item';

const App = () => (
  <BXDropdown triggerContent="Select an item">
    <BXDropdownItem value="all">Option 1</BXDropdownItem>
    <BXDropdownItem value="cloudFoundry">Option 2</BXDropdownItem>
    <BXDropdownItem value="staging">Option 3</BXDropdownItem>
    <BXDropdownItem value="dea">Option 4</BXDropdownItem>
    <BXDropdownItem value="router">Option 5</BXDropdownItem>
  </BXDropdown>
);

render(<App />, document.getElementById('root'));

Vue

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

Other usage guides

Getting started with development

Fork this repository and clone it
yarn install
yarn storybook

Running React/Angular/Vue Storybook demo

React: yarn storybook:react (Live demo: https://carbon-custom-elements-react.netlify.com/)
Angular: yarn storybook:angular (Live demo: https://carbon-custom-elements-angular.netlify.com/)
Vue: yarn storybook:vue (Live demo: https://carbon-custom-elements-vue.netlify.com/)

List of available components

View available web components at: https://carbon-custom-elements.netlify.com/. You can see usage information in several ways:

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
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 cose 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.

Iteration plans

Creating build

> yarn clean
> yarn build

You'll see the build artifacts in /path/to/carbon-custom-elements/es directory.

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

bwittenbrook3/carbon-custom-elements

carbon-custom-elements