Carbon for IBM.com Web Components
npm install @carbon/ibmdotcom-web-componentsA 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.
- 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
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 useslit for reactive templating on top oflit/decorators
raw Web Components standard and for reactivelit
properties/attributes on top of .
#### 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.

> 💡 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 agrid-column-16
requirement for Carbon for IBM.com styles, especially using the
Expressive theme.
3. Carbon Sass feature flag. This is a requirement for Carboncarbon-components
for IBM.com styles as the design prefers Carbon 16 columns grid over
library's default 12 columns grid.
Here's an example for WebPack:
`javascriptautoprefixer
module: {
rules: [
{
test: /\.scss$/,
sideEffects: true,
use: [
'style-loader',
'css-loader',
{
loader: 'postcss-loader',
options: {
postcssOptions: {
// is a requirement for Carbon core Sass codeenable-css-custom-properties
plugins: [autoprefixer],
},
},
},
{
loader: 'sass-loader',
options: {
implementation: require('sass'),
sassOptions: {
includePaths: ['../node_modules', '../../../node_modules'],
// 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
`css`
c4d-button-group:not(:defined) {
display: none;
}
#### Process.env Error
There are references to the process.env global variable in the ourprocess.env.*
web-components package and dependencies. If a build toolchain (e.g. WebPack’s
EnvironmentPlugin) to replace is not used in your application,polyfills.ts
you can place the following code in the file of your application.
`javascript`
(window as any).process = {
env: { DEBUG: undefined },
};
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.

#### 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.
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">
...
> 💡 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
$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;
}
`#### 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.
Can be found at here.
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.