@carbon/ibmdotcom-web-components

A Carbon for IBM.com variant that is as easy to use as native HTML elements, with no framework tax, no framework silo.

@carbon/ibmdotcom-web-components

@carbon/ibmdotcom-web-components is a variant of Carbon for IBM.com with Custom Elements v1 and Shadow DOM v1 specs.

Table of contents

• Getting started
• Usage Examples
  • Webpack Application Setup
    • Basic Setup
    • Using Sass
    • Process.env Error
  • CDN Bundles
    • Versioned Bundles
  • Using with other design systems (e.g Northstar v18)
• Browser support
• List of available components
• Stable selectors (for analytics and integration/E2E testing) in Web Components
• Advanced
  • Using custom styles in components
    • Creating derived components with different style
    • Using CSS Custom Properties
    • CSS Shadow Parts
    • Advanced usage for IBM.com site owners
• Contributing to Carbon for IBM.com Web Components

Getting started

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

npm install -S @carbon/ibmdotcom-web-components

If you prefer Yarn, use the following command instead:

yarn add @carbon/ibmdotcom-web-components

NOTE: Lit dependencies will be managed by Carbon for IBM.com starting in v1.13.0. For earlier versions, Lit dependencies will have to be installed separately:

npm:

npm install -S lit-html lit-element

Yarn:

yarn add lit-html lit-element

@carbon/ibmdotcom-web-components uses lit for reactive templating on top of raw Web Components standard and lit/decorators for reactive properties/attributes on top of lit.

Usage Examples

Webpack Application Setup

Basic Setup

For production usage, our recommendation is setting up a module bundler to resolve ECMAScript imports.

You can start with a minimum configuration for most module bundlers. For example, with WebPack, you don't need any configuration.

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

import '@carbon/ibmdotcom-web-components/es/components/masthead/masthead-container';

Once you do that, you can use our components as easy as using HTML tags, like:

<c4d-masthead-container></c4d-masthead-container>

Check our CodeSandbox example implementation.

Above CodeSandbox example uses html-webpack-plugin to let WebPack server serve the .html file, but you can use other means to serve .html files, for example, using Express server.

Using Sass

While styles are included as part of the web components, setting up Sass toolchain is often useful for styling your contents.

To use Sass, you can add a Sass toolchain to your module bundler. A couple of key settings needed in the Sass toolchain are:

1. autoprefixer. This is a requirement for using Carbon core Sass code.
2. enable-css-custom-properties Carbon Sass feature flag. This is a requirement for Carbon for IBM.com styles, especially using the Expressive theme.
3. grid-column-16 Carbon Sass feature flag. This is a requirement for Carbon for IBM.com styles as the design prefers Carbon 16 columns grid over carbon-components library's default 12 columns grid.

Here's an example for WebPack:

module: {
  rules: [
    {
      test: /\.scss$/,
      sideEffects: true,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'postcss-loader',
          options: {
            postcssOptions: {
              // `autoprefixer` is a requirement for Carbon core Sass code
              plugins: [autoprefixer],
            },
          },
        },
        {
          loader: 'sass-loader',
          options: {
            implementation: require('sass'),
            sassOptions: {
              includePaths: ['../node_modules', '../../../node_modules'],
              // `enable-css-custom-properties` and `grid-columns-16` feature flags
              // are requirements for Carbon for IBM.com styles
              data: `
                $feature-flags: (
                  enable-css-custom-properties: true,
                  grid-columns-16: true,
                );
              `,
            },
          },
        },
      ],
    },
  ],
},

Check our CodeSandbox example implementation.

To prevent a flash of unstyled content (FOUC) from happening on your page be sure to to display: none if a component has not been defined yet. For example

c4d-button-group:not(:defined) {
  display: none;
}

Process.env Error

There are references to the process.env global variable in the our web-components package and dependencies. If a build toolchain (e.g. WebPack’s EnvironmentPlugin) to replace process.env.* is not used in your application, you can place the following code in the polyfills.ts file of your application.

(window as any).process = {
  env: { DEBUG: undefined },
};

CDN Bundles

To get an application running without the need for front-end bundlers, there are pre-built CDN bundles available for each individual component.

Here is an example of implementing the dotcom-shell:

<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      import 'https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/latest/dotcom-shell.min.js';

      // The minimum prerequisite to use our service for translation data, etc.
      window.digitalData = {
        page: {
          pageInfo: {
            language: 'en-US',
            ibm: {
              country: 'US',
              siteID: 'IBMTESTWWW',
            },
          },
          isDataLayerReady: true,
        },
      };
    </script>
    <style type="text/css">
      body {
        font-family: 'IBM Plex Sans', 'Helvetica Neue', Arial, sans-serif;
        margin: 0;
      }
    </style>
    <!-- The minimum prerequisite to use our locale selector -->
    <link rel="alternate" hreflang="en-us" href="https://www.ibm.com/us-en/" />
    <link rel="alternate" hreflang="x-default" href="https://www.ibm.com" />
    ...
  </head>
  <body>
    <c4d-dotcom-shell-container></c4d-dotcom-shell-container>
  </body>
</html>

Carbon CDN style helpers (optional)

There are optional CDN artifacts available that can assist with global Carbon styles in lieu of including into your specific application bundle.

For example, the following adds Carbon reset and necessary Plex fonts to the page:

<!DOCTYPE html>
<html>
  <head>
    <link
      rel="stylesheet"
      href="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/latest/plex.css" />
    ...
  </head>
</html>

Learn more about Carbon CDN style helpers here

Refer to "Building for IBM.com' page for window.digitalData and <link rel="alternate" ...>.

Check our CodeSandbox example implementation.

Versioned Bundles

The CDN packages are available by NPM tags latest (full releases), next (latest release candidate), and specific versions. The URL pattern for import would be:

<script
  type="module"
  src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/version/[VERSION]/dotcom-shell.min.js"></script>

or

<script type="module">
  import 'https://1.www.s81c.com/common/carbon-for-ibm-dotcom/version/[VERSION]/dotcom-shell.min.js';
</script>

A tag release would be called as:

<!-- LATEST -->
<script
  type="module"
  src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/latest/dotcom-shell.min.js"></script>

<!-- NEXT -->
<script
  type="module"
  src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/next/dotcom-shell.min.js"></script>

A specific release would be called as:

<!-- SPECIFIC VERSION (available starting v1.6.0) -->
<script
  type="module"
  src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/version/v2.x.y/dotcom-shell.min.js"></script>

NOTE: The latest/next tags are moving versions. While beneficial to always stay on the most recent version, it is recommended to choose a specific version and properly test your application when upgrading to a newer version.

Using with other design systems (e.g Northstar v18)

Shadow DOM, one of the standards used in Carbon for IBM.com Web Components, isolates the web component styles from the application styles. This means those two styles won't adversely affect each other.

For applications that are currently running on other design systems like legacy Northstar v18, such isolation will assist with gradual migration from legacy IBM.com Northstar v18 styles to Carbon for IBM.com styles. Both technologies can co-exist safely in the same application. Here is an example with the Carbon for IBM.com masthead and legacy IBM.com Northstar footer:

<!-- Loads legacy IBM.com Design System (Northstar) -->
<link rel="stylesheet" href="https://1.www.s81c.com/common/v18/css/www.css" />
<script src="https://1.www.s81c.com/common/v18/js/www.js"></script>
<!-- Loads Carbon for IBM.com Web Components masthead -->
<script
  type="module"
  src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v1/latest/masthead.min.js"></script>

...

<body id="ibm-com" class="ibm-type">
  <div id="ibm-top" class="ibm-landing-page">
    <!-- Uses Carbon for IBM.com Web Components masthead -->
    <c4d-masthead-container></c4d-masthead-container>
    <div id="ibm-content-wrapper">...</div>
    <!-- Uses legacy IBM.com Design System (Northstar) footer -->
    <footer role="contentinfo" aria-label="IBM"></footer>
  </div>
</body>

Above example requires setting up a module bundler, as discussed in earlier section.

Check our CodeSandbox example implementation.

Browser support

Based on ibm.com browser support:

• Latest Chrome/Safari/FF ESR
• IE and classic Edge are not supported

List of available components

View available web components at: https://www.ibm.com/standards/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 bx-modal-closed which typically indicates that an event with such event type is fired.

Stable selectors (for analytics and integration/E2E testing) in Web Components

Can be found at here.

Advanced

Using custom styles in components

As Shadow DOM (one of the Web Components specs that @carbon/ibmdotcom-web-components uses) promises, styles that @carbon/ibmdotcom-web-components defines does not affect styles in your application, or vice versa.

However, in cases where your application or a Carbon-derived style guide wants to change the styles of our components, there are a few options.

Creating derived components with different style

You can create a derived class of our component and override static styles property, like:

import { css, customElement } from 'lit';
import C4DLinkWithIcon from '@carbon/ibmdotcom-web-components/es/components/link-with-icon/link-with-icon';

@customElement('my-link-with-icon')
class MyLinkWithIcon extends C4DLinkWithIcon {
  // Custom CSS to enforce `g100` color of the link text
  static styles = css`
    ${C4DLinkWithIcon.styles}
    .bx--link-with-icon {
      color: #3d70b2;
    }
  `;
}

Using CSS Custom Properties

Changes to CSS Custom Properties of the Carbon theme are reflected in the color scheme of @carbon/ibmdotcom-web-components components:

For example, if you add CSS like below:

c4d-link-with-icon {
  --c4d-link-01: #3d70b2; /* `$link-01` token for `g100` theme */
}

The color of the link in the code below changes to the one in the g100 theme:

<c4d-link-with-icon
  href="https://www.ibm.com/standards/carbon"
  cta-type="local">
  Link text
</c4d-link-with-icon>

The names of CSS Custom Properties you can use are the Carbon theme tokens prefixed with --cds-. The list of Carbon theme tokens can be found at here.

With CSS Custom Properties approach, you can switch the entire theme under the specific element by:

@use '@carbon/styles/scss/themes' as *;

c4d-link-with-icon {
  // Emits all theme tokens in CSS Custom Properties
  @include theme(g100, true);
}

CSS Shadow Parts

Some components support CSS Shadow Parts too, so you can use your application's CSS to affect @carbon/ibmdotcom-web-components styles in a more flexible manner.

For example, below style changes back button's text color in <cds-locale-modal> to one of g100 theme:

cds-locale-modal::part(back-button) {
  color: #152935;
}

Warning
While shadow parts selectors are available as an option, use them at your own risk. Changing component styles may cause components to not behave as expected. You are responsible for ensuring your components remain functional while using shadow parts selectors. We cannot guarantee updates to our library's component styles won't conflict with shadow part modifications.

Advanced usage for IBM.com site owners

There are some other key advanced usage patterns that are suitable for IBM.com site owners. IBM.com site owners can see them at here.

Contributing to Carbon for IBM.com Web Components

Can be found at here.

IBM Telemetry

This package uses IBM Telemetry to collect de-identified and anonymized 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.