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:

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

If you prefer Yarn, use the following command
instead:

`bash
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:
>
> `bash
> npm install -S lit-html lit-element
> `
>
> Yarn:
>
> `bash
> 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

$3

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

`javascript
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:

`html

`

> 💡 Check our
> CodeSandbox
> example implementation.

![Edit @carbon/ibmdotcom-web-components](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/webpack-basic)

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

`javascript
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.

![Edit @carbon/ibmdotcom-web-components](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/webpack-sass)

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

`css
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.

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

$3

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:

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

`html



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


`

Learn more about Carbon CDN style helpers here

> 💡 Refer to
> "Building for IBM.com'
> page for window.digitalData and .

> 💡 Check our
> CodeSandbox
> example implementation.

![Edit @carbon/ibmdotcom-web-components](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/dotcom-shell-cdn)

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

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

or

`html

`

A tag release would be called as:

`html

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


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

A specific release would be called as:

`html

type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/version/v2.x.y/dotcom-shell.min.js">
`

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

$3

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:

`html




type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v1/latest/masthead.min.js">

...

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

$3

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:

`javascript
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:

`css
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:

`html
href="https://www.ibm.com/standards/carbon"
cta-type="local">
Link text

`

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:

`scss
@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
to one of g100 theme:

`css
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.