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 is a variant of Carbon for IBM.com with
Custom Elements v1 and Shadow DOM v1 specs.
- Getting started
- Usage Examples
- Browser support
- List of available components
- Stable selectors (for analytics and integration/E2E testing) in Web Components
- Advanced
- 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:
npm install -S @carbon/ibmdotcom-web-componentsIf you prefer Yarn, use the following command instead:
yarn add @carbon/ibmdotcom-web-componentsNOTE: 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-elementYarn:
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.
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-pluginto let WebPack server serve the.htmlfile, but you can use other means to serve.htmlfiles, for example, using Express server.
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:
-
autoprefixer. This is a requirement for using Carbon core Sass code. -
enable-css-custom-propertiesCarbon Sass feature flag. This is a requirement for Carbon for IBM.com styles, especially using the Expressive theme. -
grid-column-16Carbon Sass feature flag. This is a requirement for Carbon for IBM.com styles as the design prefers Carbon 16 columns grid overcarbon-componentslibrary'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;
}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 },
};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>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.digitalDataand<link rel="alternate" ...>.
💡 Check our CodeSandbox example implementation.
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.
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.
Based on ibm.com browser support:
- Latest Chrome/Safari/FF ESR
- IE and classic Edge are not supported
View available web components at: https://www.ibm.com/standards/carbon/web-components/. You can see usage information in several ways:
- Going to Docs tab, where it shows the usage and available attributes, properties and custom events.
- Clicking the KNOBS tab at the bottom and changing values there. Most
knobs are shown as something like
Button kind (kind), wherekindis the attribute name - Clicking the ACTION LOGGER tab at the bottom and interacting with the
selected component. You may see something like
bx-modal-closedwhich typically indicates that an event with such event type is fired.
Can be found at here.
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.
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;
}
`;
}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);
}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;
}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 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.