Skip to main contentCarbon Design System

Guide

Here you can find information on how to migrate your code from Carbon v10 to v11. As with any major version, there are some exciting features we’re looking forward to sharing with you. We hope to make your transition as smooth as possible by detailing all of the updates below.

Changelog

Feature
Status
MigratePackages or components impacted
@carbon/react
Breaking
Componentscarbon-components-react carbon-icons carbon-components
@carbon/styles
Breaking
Stylescarbon-components @carbon/react carbon-components-angular carbon-components-vue
Color Tokens
Breaking
Color tokensAll components
CSS Grid
Breaking
CSS Grid@carbon/grid Grid Row Column
Layer Component
Breaking
LayeringComponents using light prop
Theme Component
New
Theming
carbon-icons
Deprecated
Components
carbon-components
Deprecated
Styles
carbon-components-react
Deprecated
Components

Components
Breaking

We have deprecated carbon-components-react, carbon-icons and carbon-components in favor of our new package @carbon/react. All of the component usage and API remains the same. The big change with this is to avoid having to install three separate packages that you have to keep in sync.

What this means for you and your team

Going forward, using our components and styles will be as easy as just installing or updating one package.

How to migrate

  1. Install the new package
npm -i @carbon/react
yarn add @carbon/react
  1. Remove the old packages
npm uninstall carbon-components carbon-components-react carbon-icons
yarn remove carbon-components carbon-components-react carbon-icons
  1. Update package imports. Migration for this can be as easy as find-and-replace. Search for anywhere you’re importing components or icons and update the import to point to @carbon/react. Read the next section below to find out how to migrate styles.
import { Button } from '@carbon/react';
function MyComponent() {
  return <Button>Example usage</Button>;
}
import { Add16 } from '@carbon/react/icons';
function MyComponent() {
  return <Add16 />;
}

Resources

@carbon/react docs

Styles
Breaking

In v11, our Carbon styles feature two essential changes: their own dedicated package, @carbon/styles, and transitioning to Sass modules. If you’re using our React components we have some great news for you, you don’t have to install the styles package! @carbon/react already forwards all the sass included in @carbon/styles. If you are a library not using our React components, and just consuming our styles, then your migration will require installing the new package in addition to what’s listed below.

Using Dart-Sass, we are finally able to use the Module System, dropping the import-once helpers that have being causing awful compilation and build times, and re-thinking how developers bring styles into Carbon.

Here are some reasons why we’re moving away from Node-Sass and moving towards Dart-Sass:

  • Import Once: To offer better flexibility for importing Sass files, the project used a convention to offer style deduplication due to Sass’s @import behavior.
  • Long compile times: While this technique would compile fine using Sass CLIs directly, tooling like sass-loader would take an increasingly large amount of time.
  • Incorrect behavior: In certain configurations with Webpack <4 and sass-loader, style duplication was not even being prevented.
  • LibSass deprecation: When LibSass was deprecated, and subsequently node-sass, we knew it was time to start looking towards Dart Sass.

What this means for you and your team

  • Faster compile times
  • Faster build times
  • Over-all more flexibility when importing styles

How to migrate

  1. Projects that are currently using webpack with sass-loader the update should be automatic.
  2. Projects using create-react-app or Next.js, remove node-sass from your dependencies and add sass as the replacement.
  3. In any of your files where you are using Carbon sass (tokens, mixins, or funcions), you will now need to import the specific sass file at the top. You will use the @use keyword instead of @import to include the Carbon sass, as seen below. If you’re using our React components, your import will point to the @carbon/react package. If you’re a library just using the styles package, your import will point to that.
@use '@carbon/react/scss/theme';
body {
  background: theme.$background;
}

Alternatively, if you don’t want to deal with prefixing all the Carbon sass instances, you can do the following:

@use '@carbon/react/scss/theme' as *;
body {
  background: $background;
}

To learn more about getting starting with Dart Sass, usage, and importing specific Carbon sass, checkout our styles docs.

Resources

@carbon/styles docs
Migrating from node-sass to dart-sass

Color Tokens
Breaking

We have renamed our color tokens to be more semantic and better inform on their usage. Some of the changes can be easily done with find-and-replace, however, some may require more manual updates. When migrating, make sure to double check that you were using the correct v10 token as to not migrate to an incorrect token.

What this means for you and your team

  • Intuitive naming ensures correct token usage
  • Less ambiguity around what a color token is for

How to migrate

  1. Check for any sass files that are referencing color tokens, and use our color token migration table to find the updated token name. We recommend checking manually since some of the v10 tokens apply to more than one v11 token, depending on its usage. For example, hover-ui could be field-hover or layer-hover.

To view a full table of v10 color tokens and their v11 equivalent, check out our colors migration doc.

Resources

Color tokens migration table

CSS Grid
Breaking

A huge change for us this release is dropping support for IE11, which means we can now support CSS Grid. 🎉 Previously, our grid used CSS Flexbox, which made it hard to support nesting grids. At the moment, we are not providing an option to continue using flexbox grid in v11. Another notable change is that, by default, our grid is now 16 columns and there is no continued support for 12 columns.

What this means for you and your team:

  • 16 column grid only
  • Support for nested grids

How to migrate

Grid and Column continue to have the same props, but operate just a little bit differently. We realize the strategy for updating the grid might change from team to team, so instead we’re just going to highlight some of the big changes you need to keep in mind when tackling this transition.

  • If you are using a 3 column layout anywhere, we suggest talking to your design team to decide on an alternate layout since we are no longer supporting 12 columns. We realize this may be frustrating, but we hope the other cool features we now support make it worth the change!
  • Use Grid component for subgrids.
  • Row component is deprecated. You can drop Column components directly into Grid, including nested grids.
  • All columns by default will span just one column, not span the full width like flex columns. You must be explicit about how many columns you want to span for each breakpoint. Below, you can find what a full width 4 column layout would’ve looked like in v10 and what it looks like now in v11.
  • To view more detailed examples of our v11 grid, checkout our grid story.

Some usage guidelines to keep in mind when migrating are:

  • Wide grid should always be the parent grid
  • Some grids, like condensed grid, don’t exist in isolation; they are always mixed.

v10 auto columns

<Grid>
  <Row>
    <Column>1 of 4</Column>
    <Column>1 of 4</Column>
    <Column>1 of 4</Column>
    <Column>1 of 4</Column>
  </Row>
</Grid>

v11 auto columns

<Grid>
  // first row - 4 col full span like the v10 auto columns
  <Column lg={4}>1 of 4</Column>
  <Column lg={4}>1 of 4</Column>
  <Column lg={4}>1 of 4</Column>
  <Column lg={4}>1 of 4</Column>
  // second row - v11 auto columns
  <Column>1 of 8</Column>
  <Column>1 of 8</Column>

Nested grid

<Grid>
  <Column sm={2} md={4} lg={3}>
    <p>Small: Span 2 of 4</p>
    <p>Medium: Span 4 of 8</p>
    <p>Large: Span 3 of 16</p>
  </Column>
  <Column sm={2} md={4} lg={10}>
    <p>Small: Span 2 of 4</p>
    <p>Medium: Span 4 of 8</p>

Resources

CSS Grid docs
CSS Grid storybook
react icon

Theming

With our theming updates we have some new features and some breaking changes. You can now specify you’re theme with our new Theme component., and incorporate inline theming. You can also specify a layer with a Layer component.

Layer Component
Breaking

In regards to theming, we have also added in a new Layer component. The Layer component replaces the light prop. It is a container that renders the cds--layer class name. The class name then remaps contextual tokens to the next layer. This allows you to style different layers, or directly use the tokens exported from our styles package.

What this means for you and your team

  • Layer componet replaces light prop. See the first example below.
  • More flexibility for 3 layer stacking vs. 2 layer stacking
  • Third layer stacking will now be supported in dark themes
  // v10
  <Dropdown light />
  // v11
  <Layer>
    <Dropdown />
  </Layer>

Here is an example of how you can use the Layer component:

<Layer>
  <ChildComponent />
  <Layer>
    <ChildComponent />
    <Layer>
      <ChildComponent />
    </Layer>
  </Layer>
</Layer>

To learn more about how our Layer component works and it’s API, checkout out the resource link below.

Theme Component
New

We have added a new, flexible Theme component. The Theme component allows you to specify the theme for a section of the page, for example with inline theming, or render a theme for an entire page.

What this means for you and your team

  • Inline theming 🎉

Here is an example of how you can use the Theme component:

<Theme theme="g90">
  <ChildComponent />
</Theme>

To learn more about how our Theme component works with our useTheme hook, checkout our resource link below.

Resources

Layer component docs
Theme component docs
Edit this page on GitHub
Previous
Guide: Design
Next
Migrating: FAQs