❤
npm
Sign UpSign In

@carbon/web-components
TypeScript icon, indicating that this package has built-in type declarations

2.8.0 • Public • Published

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

Carbon Design System

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 is released under the Apache-2.0 license

This project is using Percy.io for visual regression testing

@carbon/web-components

@carbon/web-components is a variant of Carbon Design System with Custom Elements v1 and Shadow DOM v1 specs.

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/v2/latest/accordion.min.js"></script>

<!-- By specific version -->
<script
  type="module"
  src="https://1.www.s81c.com/common/carbon/web-components/version/v2.0.0/accordion.min.js"></script>
See full 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-icon.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

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/v2/latest/dropdown.min.js"></script>
    <style type="text/css">
      // Suppresses the custom element until it has been defined
      cds-dropdown:not(:defined),
      cds-dropdown-item:not(:defined) {
        visibility: hidden;
      }
    </style>
  </head>
  <body>
    <div id="app">
      <cds-dropdown trigger-content="Select an item">
        <cds-dropdown-item value="all">Option 1</cds-dropdown-item>
        <cds-dropdown-item value="cloudFoundry">Option 2</cds-dropdown-item>
        <cds-dropdown-item value="staging">Option 3</cds-dropdown-item>
        <cds-dropdown-item value="dea">Option 4</cds-dropdown-item>
        <cds-dropdown-item value="router">Option 5</cds-dropdown-item>
      </cds-dropdown>
    </div>
  </body>
</html>

Our example at CodeSandbox shows usage with only CDN artifacts:

Edit carbon-web-components

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 --save @carbon/web-components

If you prefer Yarn, use the following command instead:

yarn add @carbon/web-components

Basic usage

Our example at CodeSandbox shows the most basic usage:

Edit carbon-web-components

The first thing you need is setting 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:

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

Other usage guides

JavaScript framework support

This package also supports integration with other JavaScript frameworks like Angular and Vue. 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:

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, for example:

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 files in @carbon/web-components package are compiled with TypeScript 3.7. You can use TypeScript 3.7 in your Angular application with upcoming Angular 9.0 release, or with the following instructions, so your application can use those .d.ts files:

Vue

Edit carbon-web-components with Vue

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

Getting started with development

  1. Fork this repository and clone it
  2. yarn install
  3. cd packages/carbon-web-components
  4. yarn wca && yarn storybook

List of available components

View available web components at: https://www.ibm.com/standards/carbon/carbon-web-components. 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 cds-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

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

IBM Telemetry 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.

Readme

Keywords

Package Sidebar

Install

npm i @carbon/web-components

Repository

github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main

Homepage

github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main#readme

Weekly Downloads

11,250

Version

2.8.0

License

Apache-2.0

Unpacked Size

26.7 MB

Total Files

19868

Last publish

Collaborators

  • guidari
  • flucca
  • dmenend
  • jdharvey
  • carbon-design-system
  • carbon-bot
  • tjegan
  • alisonjoseph
  • leechase
  • jeffreychew
  • simonfinney
  • sstrubberg
  • andreancardona
  • tay1orjones
Try on RunKit
Report malware