styling.md

Using custom styles in components

As Shadow DOM (one of the Web Components specs that @carbon/web-components uses) promises, styles that @carbon/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.

• Using CSS Custom Properties
• Dependency injection
• Creating derived components with different style

Using CSS Custom Properties

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

For example, if you add CSS like below:

footer {
  --cds-interactive-02: #6f6f6f; /* `$interactive-02` token for `g100` theme */
}

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

<footer>
  <cds-button kind="secondary">Secondary button</cds-button>
</footer>

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/reset';
@use '@carbon/styles/scss/theme';
@use '@carbon/styles/scss/themes';

footer {
  @include theme.theme(themes.$g100);
} // Emits all theme tokens in CSS Custom Properties

Some components such as Button, Notification, & Tag have specific tokens per theme that need to emitted in the styles. You can do this for example by adding the following:

@use '@carbon/styles/scss/reset';
@use '@carbon/styles/scss/theme';
@use '@carbon/styles/scss/themes';
@use '@carbon/styles/scss/components/button/tokens' as button-tokens;
@use '@carbon/styles/scss/components/notification/tokens' as notification-tokens;
@use '@carbon/styles/scss/components/tag/tokens' as tag-tokens;
@include theme.add-component-tokens(button-tokens.$button-tokens);
@include theme.add-component-tokens(notification-tokens.$notification-tokens);
@include theme.add-component-tokens(tag-tokens.$tag-tokens);

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 CDSDropdown from '@carbon/web-components/es/components/dropdown/dropdown';

@customElement('my-dropdown')
class MyDropdown extends CDSDropdown {
  // Custom CSS to enforce `field-02` (light) style of the dropdown
  static styles = css`
    ${CDSDropdown.styles}
    .cds--list-box {
      background-color: white;
    }
  `;
}