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
Components
Styles
Color Tokens
CSS Grid
Layering
Theming

Changelog

Feature	Status	Migrate	Packages or components impacted
`@carbon/react`	Breaking	Components	`carbon-components-react` `carbon-icons` `carbon-components`
`@carbon/styles`	Breaking	Styles	`carbon-components` `@carbon/react` `carbon-components-angular` `carbon-components-vue`
Color Tokens	Breaking	Color tokens	All components
CSS Grid	Breaking	CSS Grid	`@carbon/react` `@carbon/grid`
Component `size` prop	Breaking	CSS Grid	`@carbon/react` components that have different size variations
Icons `size` prop	Breaking	Icons size prop	`@carbon/react/icons` `@carbon/icons-react` All icons
Component `className` prop	Breaking	CSS Grid	`@carbon/react`
Event handlers	Breaking	CSS Grid	`@carbon/react`
Notification	Breaking	CSS Grid	`@carbon/react`
Tooltip	Breaking	CSS Grid	`@carbon/react`
ContentSwitcher	Breaking	CSS Grid	`@carbon/react`
Layer Component	Breaking	Layering	Components using `light` prop
Theme Component	New	Theming
Popover	New	New components	`@carbon/react` `carbon-components`
ToggleTip	New	New components	`@carbon/react` `carbon-components`
Dialog	New	New components	`@carbon/react` `carbon-components`
`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

Install the new package

npm i @carbon/react

yarn add @carbon/react

Remove the old packages

npm uninstall carbon-components carbon-components-react carbon-icons

yarn remove carbon-components carbon-components-react carbon-icons

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

Projects that are currently using webpack with sass-loader the update should be automatic.
Projects using create-react-app or Next.js, remove node-sass from your dependencies and add sass as the replacement.
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 or read about it from a developer’s perspective in this Medium article. Checkout a live example of mixins and design tokens using the Carbon tutorial.

Resources

@carbon/styles docs

Migrating from node-sass to dart-sass

One quick way to get ready for Carbon v11

Discover mixins using the Carbon tutorial

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

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

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 usage docs. You can also checkout a live example of the Carbon Tutorial to see theming in action.

Resources

Theme usage example

Theme component docs

Layer component docs

Updates to `@carbon/icons-react`

We have two new changes to our @carbon/icons-react package. We have updated the default prop size and the way it can be imported.

Icon size prop

We are updating the default size prop for all icons to md.

Importing

All icons can now be imported from @carbon/react/icons. In v11, you’ll still be able to access @carbon/icons-react, however it is available directly from the @carbon/react package, by default.

Here is an example of how to import an icon:

import { Add } from '@carbon/react/icons';

Component API

Size prop updates
Breaking

We updated all our components with size variants to have the same API. Previously, the size options were inconsistent: field, medium, short. Sizing options will now be the same across all components for less confusion.

What this means for you and your team

You will always know what to expect from components to size correctly

How to migrate

The following components all have size variants that may be affected in your code:

Accordion
Button
ComboBox
Dropdown
Multiselect
Filterable multiselect
ContentSwitcher
DataTable
DatePicker
FileUploader
FileUploaderItem
FileUploaderDropContainer
FileUploaderButton
Link
Modal
ComposedModal
NumberInput
OverflowMenu
Search
Select
Tag
TextInput
TimePicker
Toggle

If you are using any size variants of those listed components, use the following table to determine what updated value to use for the size prop. The default size in v11 is md (40px).

Prop value	Size
`xs`	24px
`sm`	32px
`md`	40px
`lg`	48px
`xl`	64px
`2xl`	80px

ClassName prop updates
Breaking

We updated our components to pass custom className to the outermost element of a component’s inner markup. A lot of components already placed this prop on the outermost layer, but many were targetting elements inside the wrappers.

What this means for you and your team

Easily target any component HTML element since the className is now added to the wrapper

How to migrate

The following components previously were not applying the className prop to the outermost element. If you were using a custom className to target an inner element for any of these components, you will have to update your selectors to now account for the className being in the wrapper.

Checkbox
Combobox
Table
TableToolbar
DataTableSkeleton
DatePicker
DatePickerSkeleton
DatePickerInput
Dropdown
FileUploaderDropContainer
FileUploaderItem
FormGroup
FilterableMultiSelect
MultiSelect
NotificationTextDetails
NotificationIcon
NumberInput
OverflowMenuItem
RadioButtonGroup
RadioTile
Select
Slider
Switch
TextArea
ControlledPasswordInput
PasswordInput
TextInput
TimePicker
Tooltip
HeaderContainer

Event handler updates
Breaking

Guidance coming soon.

New Components

We are releasing a few new components that complement our accessibility initiatives and component changes.

This component primitive is most similar a tile or card. However, Popover is a primitive consumed by other components to render content. Popover components can also be referred to as Disclosures, and will be accomodate a lot of the changes being made in our Tooltip component.

Learn more about our Popover component and it’s API below:

Popover

Edit this page on GitHub

Guide: Design

Migrating: FAQs

Changelog

Components Breaking

What this means for you and your team

How to migrate

Resources

@carbon/react docs

Styles Breaking

What this means for you and your team

How to migrate

Resources

@carbon/styles docs

Migrating from node-sass to dart-sass

One quick way to get ready for Carbon v11

Discover mixins using the Carbon tutorial

Color Tokens Breaking

What this means for you and your team

How to migrate

Resources

Color tokens migration table

CSS Grid Breaking

What this means for you and your team:

How to migrate

v10 auto columns

v11 auto columns

Nested grid

Resources

CSS Grid docs

CSS Grid storybook

Theming

Layer Component Breaking

What this means for you and your team

Theme Component New

What this means for you and your team

Resources

Theme usage example

Theme component docs

Layer component docs

Updates to @carbon/icons-react

Icon size prop

Importing

Component API

Size prop updates Breaking

What this means for you and your team

How to migrate

ClassName prop updates Breaking

What this means for you and your team

How to migrate

Event handler updates Breaking

New Components

Popover

Popover

Components
Breaking

Styles
Breaking

Color Tokens
Breaking

CSS Grid
Breaking

Layer Component
Breaking

Theme Component
New

Updates to `@carbon/icons-react`

Size prop updates
Breaking

ClassName prop updates
Breaking

Event handler updates
Breaking