Carbon Design System

Step-by-step guide to updating your code from Carbon v10 to v11.

Overview
carbon-components-react
carbon-components
@carbon/icons-react
carbon-icons
Elements

Overview

This guide helps you update your project to Carbon v11. It is broken into sections based on packages that you are using in your project today. For most teams using Carbon, you’ll want to use the carbon-components-react section.

One of the biggest changes coming to Carbon in v11 is that we are moving to dedicated packages under the @carbon scope. What this means for you is that if you were previously using the following packages:

carbon-components
carbon-components-react
carbon-icons
@carbon/icons-react

You can access all of this work under one single package: @carbon/react. This package will re-export all of the styles and icons for Carbon all in one dependency.

If you were previously using carbon-components, the styles from this package are available under @carbon/styles. They are also re-exported through @carbon/react

Both the carbon-components and carbon-components-react packages will stick around in v11 but they will only be re-exports of @carbon/styles and @carbon/react respectively.

Some of the migration steps below can be automated using the @carbon/upgrade CLI. For full details, see the @carbon/upgrade package documentation

carbon-components-react

Starting in v11, the React components for Carbon live in the @carbon/react package.

The @carbon/react package also includes the styles for Carbon along with icons.

Step 1: Install @carbon/react

To get started, uninstall the following packages if they exist in your project:

carbon-components
carbon-components-react
carbon-icons
@carbon/icons-react

npm uninstall carbon-components carbon-components-react carbon-icons @carbon/icons-react
Copy to clipboard

Or, with Yarn:

yarn remove carbon-components carbon-components-react carbon-icons @carbon/icons-react
Copy to clipboard

Next, install the @carbon/react package:

npm install @carbon/react
Copy to clipboard

Or, with Yarn:

yarn add @carbon/react
Copy to clipboard

Step 2: Styles and Dart Sass

If you’re importing styles from carbon-components, you can now import styles directly from @carbon/react or the @carbon/react/scss folder.

Before you’re able to bring in these styles, you’ll need to make sure your project is setup to use Dart Sass. Starting in v11, Carbon styles requires Dart Sass through the sass package in order to compile. This change comes from our migration to Sass Modules in order to improve our compilation times and overall project structure.

If you don’t have this dependency already in your project, you can install it:

npm install sass
Copy to clipboard

Or, with Yarn:

yarn add sass
Copy to clipboard

Similarly, if you currently use node-sass now is a good time to remove that dependency from your project. In most situations, Dart Sass is a drop-in replacement for node-sass and should require no changes on your end in order to use it once you install the dependency.

Step 3: Setup Dart Sass for your project

Once you have Dart Sass installed, it’s important that you configure your project to support resolving imports in Sass from node_modules. Typically, this means adding node_modules to your includePaths config for Sass in your bundler or toolchain of choice.

To learn more about how to configure your specific toolchain to support this, read the documentation for configuration here. We also have published a guide over on Medium to help out with common problems that come from this migration.

Step 4: Update style import paths

In v10, you may have been bringing in styles from carbon-components by either importing the styles directly with:

@import 'carbon-components/scss/globals/scss/styles.scss';
Copy to clipboard

Or, you imported the styles through specific entrypoints:

// Feature flags
$feature-flags: (
  enable-columns-16: true,
);
// Options
$css--default-type: true;
$css--reset: true;
// Top-level imports
@import 'carbon-components/scss/globals/scss/vars';
Copy to clipboard

If you imported the entrypoint from carbon-components, you can now do this directly from @carbon/styles without any additional paths by writing:

@use '@carbon/react';
Copy to clipboard

If you were providing any configuration options before you imported Carbon you can now provide them using the with syntax:

@use '@carbon/react' with ($css--default-type: true, $css--reset: true);
Copy to clipboard

If you were using any feature flags in v10, you can safely remove them in v11.

Note: you can also use @import to bring in Carbon, if you prefer, although @use is recommended.

If you were bringing parts of Carbon, you’ll need to update the paths to reflect the new paths in @carbon/styles. In general, most paths moved from scss/globals/scss/filename to scss/filename.

// Configuration
@use '@carbon/react/scss/config' with
  ($css--default-type: true, $css--reset: true);
// Reset
@use '@carbon/react/scss/reset';
// Grid
@use '@carbon/react/scss/grid';
// Helpers
@use '@carbon/react/scss/theme';
Copy to clipboard

For a full list of the paths that have changed in carbon-components, check out our Migration Docs.

Note: if you see any references to @carbon/styles for style imports, you can safely replace the beginning of the path with @carbon/react for the same import in this package.

Step 5: Update Sass imports

If your project is currently importing from different parts of carbon-components for specific variables, mixins, or functions then you will need to make sure that your imports have been updated to the correct path.

The full list of changes are available in our Migration Docs but, in general, most imports have been updates so that the carbon-- is no longer necessary.

Step 6: Update JavaScript imports

This step can be automated using the @carbon/upgrade CLI. For full details, see the @carbon/upgrade package documentation

Rewrite imports from carbon-components-react to @carbon/react.

npx @carbon/upgrade migrate update-carbon-components-react-import-to-scoped
Copy to clipboard

After updating how you bring in styles, you will need to update your import paths from carbon-components-react to @carbon/react for components that you’re bringing from Carbon.

// Before
import { Accordion, AccordionItem } from 'carbon-components-react';
// After
import { Accordion, AccordionItem } from '@carbon/react';
Copy to clipboard

Step 7: Update icon imports

This step can be automated using the @carbon/upgrade CLI. For full details, see the @carbon/upgrade package documentation

The @carbon/icons-react package has been updated to minimize the number of exports from the package to help reduce build and compile times. This package is available under @carbon/react/icons.

This update includes a change to the API of the icon components that come from this package. Previously, we would export icons that included the size of the asset. This update allows you to bring the icon directly and specify the size using the size prop.

Before

import { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';

function MyComponent() {
  return (
    <>
      <Add32 />
      <Add24 />
      <Add20 />
      <Add16 />
Copy to clipboard

After

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

function MyComponent() {
  return (
    <>
      <Add size={32} />
      <Add size={24} />
      <Add size={20} />
      <Add />
Copy to clipboard

With this change, you can now import icons from @carbon/react directly by writing:

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

Step 8: Update components that have changed

In v11, we have updated the APIs of certain components in one of the following ways:

Update className usage to be applied to the outermost element of a component
Update size to have consistent values across the codebase
Remove props that have been deprecated in v10
Refactor the API to ship an accessible component

For a full list of changes to components, check out our Migration Docs. Below are some common changes that may impact you and your usage of Carbon.

Changes to `className`

The usage of className prop has been updated so that the class is passed to the outermost element of a component’s inner markup. This was already the case for most components and this change brings along the remaining components in the library to this convention.

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 placed on the outermost element.

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

Changes to `size`

Components with size variants have been updated to use the same API options. Previously, the size options were inconsistent: field, medium, short. Now, size options fall under the following values:

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

Note: the default size in v11 is md (40px).

This step can be automated using the @carbon/upgrade CLI. For full details, see the @carbon/upgrade package documentation

Automate size prop changes.

npx @carbon/upgrade migrate small-to-size-props
npx @carbon/upgrade migrate size-prop-updates
Copy to clipboard

The following components all have size variants that may be affected in your code. To update, you will need to switch to one of the size options above.

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

Notification

We have updated the notification components to be more accessible out of the box. ToastNotification and InlineNotification now have role="status" by default with additional role options of log and alert. These components do not receive focus and should be used for information-only use cases. These components no longer accept actions or interactive children.

For notifications requiring an action, a new ActionableNotifiation component is available. It has a role="alertdialog" and recieves focus by default. Automatic placement of focus can be turned off via the new hasFocus prop.

All notifications have a new optional closeOnEscape prop, it enables notifications to closed by pressing the escape key. For more details, see the notification components accessibility page.

Update `ToastNotification` usage

children can no longer contain interactive elements. A ToastNotification containing an action or interactive children should be replaced with ActionableNotification.
The notificationType prop is no longer needed and can be removed.
The default role is now status. log and alert can also be used.
The closeOnEscape prop toggles the closing of notifications via the escape key.

Update `InlineNotification` usage

The actions prop has been removed. An InlineNotification containing an action or interactive children should be replaced with ActionableNotification configured with the inline prop.
children can no longer contain interactive elements.
The notificationType prop is no longer needed and can be removed.
The default role is now status. log and alert can also be used.
The closeOnEscape prop toggles the closing of notifications via the escape key.

When using `ActionableNotification`:

The inline prop enables a styling variation resulting in a similar visual design to InlineNotification.
The actionButtonLabel prop configures the action button text.
The hasFocus prop toggles the automatic placement of focus.
The closeOnEscape prop toggles the closing of notifications via the escape key.

Tabs

Tabs have been updated to be more composable so that you have the flexibity and control to make them look and act how you want.

In v10, you may have code that looks like the following:

<Tabs>
  <Tab label="Tab label 1">
    <p>Content for first tab goes here.</p>
  </Tab>
  <Tab label="Tab label 2">
    <p>Content for second tab goes here.</p>
  </Tab>
  <Tab label="Tab label 3" disabled>
    <p>Content for third tab goes here.</p>
Copy to clipboard

Those same Tabs, migrated to v11:

<Tabs>
  <TabList>
    <Tab>Tab Label 1</Tab>
    <Tab>Tab Label 2</Tab>
    <Tab disabled>Tab Label 3</Tab>
    <Tab title="Tab Label 4 shows truncation">Tab Label 4 shows truncation</Tab>
  </TabList>
  <TabPanels>
    <TabPanel>Content for first tab goes here.</TabPanel>
Copy to clipboard

Update `Tabs` and `Tab` usage

All the same functionality for Tabs is available in v11 and more! However, some props have been deprecated becuase they have either been renamed or are no longer needed. Below are the minor tweaks in naming or implementation.

the type prop is deprecated. Both “container” and “default” tabs still exist but now can be called by adding the prop contained to the TabList.
Default tabs are now referred to as line tabs in our documentation here and in our storybook.
hidden prop is no longer needed with the new composable Tabs. You have control over tab content and when it is hidden through the TabPanel and TabPanels components.
selected prop is now named selectedIndex.
tabContentClassName is no longer needed. TabPanel (equivalent to tab content) takes in a className prop on its outermost node.
For Tab, label is no longer needed. children of Tab are now the label.
Due to its composability, renderAnchor, renderButton, renderContent are no longer needed on Tab. You now have full control over what is rendered inside of Tab and TabPanel.
Because renderButton is no longer needed, the associated tabIndex prop has also been deprecated.
selected on Tab is deprecated in favor or selectedIndex, now placed on Tabs instead.

For more details about the changes to Tabs, see our storybook documentation here.

Step 9: Done with @carbon/react!

And that’s it! You’re done. At this point you have migrated to use Carbon v11 using the @carbon/react package.

If you run into any problems after this point, please feel free to reach out to us over on Slack or open up a discussion on GitHub. We want to make this migration experience as seamless as possible and will be monitoring both areas to help out.

carbon-components

Starting in v11, the styles for Carbon live in the @carbon/styles package. Alternatively, you can continue to use carbon-components as it re-exports styles from this package directly.

If you are using carbon-components-react, you can bring in styles directly from the new package @carbon/react. To learn more, visit the carbon-components-react section.

Step 1: Install @carbon/styles

To get started, uninstall carbon-components from your project:

npm uninstall carbon-components
Copy to clipboard

Or, with Yarn:

yarn remove carbon-components
Copy to clipboard

Next, install the @carbon/styles package:

npm install @carbon/styles
Copy to clipboard

Or, with Yarn:

yarn add @carbon/styles
Copy to clipboard

Step 2: Install Dart Sass

Previously, carbon-components supported being compiled by different Sass libraries. Starting in v11, the @carbon/styles package requires Dart Sass through the sass package in order to compile. This change comes from our migration to Sass Modules in order to improve our compilation times and overall project structure.

If you don’t have this dependency already in your project, you can install it:

npm install sass
Copy to clipboard

Or, with Yarn:

yarn add sass
Copy to clipboard

Step 3: Setup Dart Sass

One you have Dart Sass installed, it’s important that you configure your project to support resolving imports in Sass from node_modules. Typically, this means adding node_modules to your includePaths config for Sass in your bundler or toolchain of choice.

Step 4: Update import paths

In v10, you may have been bringing in styles from carbon-components by either importing the styles directly with:

@import 'carbon-components/scss/globals/scss/styles.scss';
Copy to clipboard

Or, you imported the styles through specific entrypoints:

// Feature flags
$feature-flags: (
  enable-columns-16: true,
);
// Options
$css--default-type: true;
$css--reset: true;
// Top-level imports
@import 'carbon-components/scss/globals/scss/vars';
Copy to clipboard

If you imported the entrypoint from carbon-components, you can now do this directly from @carbon/styles without any additional paths by writing:

@use '@carbon/styles';
Copy to clipboard

If you were providing any configuration options before you imported Carbon you can now provide them using the with syntax:

@use '@carbon/styles' with ($css--default-type: true, $css--reset: true);
Copy to clipboard

If you were using any feature flags in v10, you can safely remove them in v11.

Note: you can also use @import to bring in Carbon, if you prefer, although @use is recommended.

// Configuration
@use '@carbon/styles/scss/config' with
  ($css--default-type: true, $css--reset: true);
// Reset
@use '@carbon/styles/scss/reset';
// Grid
@use '@carbon/styles/scss/grid';
// Helpers
@use '@carbon/styles/scss/theme';
Copy to clipboard

For a full list of the paths that have changed in carbon-components, check out our Migration Docs.

Step 5: Update imports

If you were using specific variables, mixins, or functions from Carbon, it may be that you will need to update their name in v11. In general, all carbon-- prefixed names have been renamed to drop the carbon-- prefix. To remove the carbon-- prefix and update it perform a find and replace operation, as illustrated in the following example.

- @include carbon--breakpoint(lg) {
+ @include breakpoint(lg) {
      width: 42%;
  }
Copy to clipboard

For a full list of the changes to variables, mixins, and functions that have changed, check out our Migration Docs and find the specific file that you were importing from.

For a full list of the paths that have changed in carbon-components, check out our Migration Docs.

Step 6: Update bx to cds

If you are targeting specific selectors that use the bx prefix, you will need to update your code to either target the cds prefix for selectors or update Carbon’s configuration to use bx as the prefix by writing the following:

// Option A
@use '@carbon/styles' with ($prefix: 'bx');
// Option B
@use '@carbon/styles/scss/config' with ($prefix: 'bx');
Copy to clipboard

Step 7: Enable flexbox grid

If you are using the flexbox-based grid in your project, you can continue to use this feature in v11 by importing the following:

@use '@carbon/styles/scss/grid/flexbox';
Copy to clipboard

This is important due to the fact that the CSS Grid implementation is used by default in v11. However, bringing in the flexbox grid styles in this way means that your layouts will continue to work the same as in v10.

Step 8: Update color tokens

If you are using color tokens from Carbon, you can either update to use the new tokens in v11 or use the compatability theme for incremental adoption of the new tokens while maintaining existing work from v10.

For an overview of the changes to tokens, check out our Migration Docs.

If you would like to use the compatability theme, you can write the following in your project where you are currently bringing in theme:

@use '@carbon/themes/scss/compat/themes' as compat;
@use '@carbon/themes/scss/themes';
@use '@carbon/themes/scss/theme' with
  ($fallback: compat.$g100, $theme: themes.$g100);
Copy to clipboard

Doing this will allow you to use tokens from the g100 theme in v10 along with the tokens in v11. This will work for any of the themes in v10 including white, g10, g90, and g100.

Other tokens that were deprecated in V11, like those in the Spacing, Motion, and Type packages, have been reexported as of @carbon/react@1.30.0 and do not need to be migrated immediately.

Step 9: Done with @carbon/styles!

And that’s it! You’re done. At this point you have migrated to use Carbon v11 using the @carbon/styles package.

@carbon/icons-react

The @carbon/icons-react package has been updated to minimize the number of exports from the package to help reduce build and compile times. It also has been updated to remove icons that were deprecated in v10.

If you are using @carbon/react, you can now import icons directly from @carbon/react/icons.

Changes to size

Before

import { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';

function MyComponent() {
  return (
    <>
      <Add32 />
      <Add24 />
      <Add20 />
      <Add16 />
Copy to clipboard

After

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

function MyComponent() {
  return (
    <>
      <Add size={32} />
      <Add size={24} />
      <Add size={20} />
      <Add />
Copy to clipboard

Removed icons

The following deprecated icons have been removed. Use the table below to find their replacement, if available, in v11.

Asset	v10	v11
app-switcher	AppSwitcher	Switcher
arrows	Arrows	ArrowsVertical
back-to-top	BackToTop	UpToTop
checkbox—undeterminate	CheckboxUndeterminate	CheckboxIndeterminate
checkbox—undeterminate—filled	CheckboxUndeterminateFilled	CheckboxIndeterminateFilled
cloud—lightning	CloudLightning	Removed
cloud—rain	CloudRain	Removed
cloud—snow	CloudSnow	Removed
delete	Delete	TrashCan
edit-filter	EditFilter	FilterEdit
sunny	Sunny	Removed
research—bloch-sphere	ResearchBlockSphere	BlochSphere
research—hinton-plot	ResearchHintonPlot	HintonPlot
research—matrix	ResearchMatrix	Matrix
misuse—alt	MisuseAlt	MisuseOutline
logo—google	LogoGoogle	Removed
mammogram—stacked	MammogramStacked	Removed
logo—delicious	LogoDelicious	Removed
logo—stumbleupon	LogoStumbleUpon	Removed
letter—Aa—large	LetterAaLarge	TextFont
glyph—caution-inverted	GlyphCautionInverted	CautionInverted
glyph—caution	GlyphCaution	Caution
glyph—circle-fill	GlyphCircleFill	CircleFill
glyph—circle-stroke	GlyphCircleStroke	CircleStroke
glyph—critical	GlyphCritical	Critical
glyph—incomplete	GlyphIncomplete	Incomplete
glyph—square-fill	GlyphSquareFill	SquareFill
glyph—undefined	GlyphUndefined	Undefined

Migration

Most use-cases of the icons from the @carbon/icons-react package will be covered by an automated codemod. To run this codemod, follow the instructions in @carbon/upgrade.

Update imports and size usage for @carbon/icons-react

npx @carbon/upgrade migrate icons-react-size-prop
Copy to clipboard

However, in certain situations, we will be unable to infer what the correct update should be for a certain usage of the icon component. We have written the codemod to work for most situations, but you will see console warnings for files that will require you to manually review them to make sure the transforms were applied correctly.

The most common manual update that teams will need to make is if a prop where the icon is passed to places a ref on the icon. For example,

function MyComponent({ renderIcon: Icon }) {
  const ref = useRef(null);
  return <Icon ref={ref} />;
}

// Before
<MyComponent renderIcon={Search16} />

// After the codemod
Copy to clipboard

In this situation, you will need to update your code to use React.forwardRef:

<MyComponent
  renderIcon={React.forwardRef((props, ref) => (
    <Search ref={ref} size={16} {...props} />
  ))}
/>;

// Or, alternatively:
const Search16 = React.forwardRef((props, ref) => {
  return <Search ref={ref} size={16} {...props} />;
Copy to clipboard

Manual migration

In addition to the automated codemods above, there are several patterns in your codebase that you will need to update manually:

If you use the name ForwardRef(IconName16) in a test you will need to manually change this. Prefer to use the component directly if using enzyme
If you use snapshot tests, the structure will change and include a size prop. Make sure that the size prop value matches what your icon name used to be. For example, <Add16 /> should become <Add size={16} />

carbon-icons

The carbon-icons package has been deprecated and is no longer supported. To use icons from the Carbon Design System, you should install the appropriate library to use with your framework:

Package	Framework	Link
`@carbon/icons-react`	React	Link
`@carbon/icons-angular`	Angular	Link
`@carbon/icons-vue`	Vue	Link
`carbon-icons-svelte`	Svelte	Link
`@carbon/icons`	Vanilla JavaScript	Link

If you are using @carbon/react, you can directly import icons from @carbon/react/icons.

Elements

The packages that we ship for the IBM Design Language have been updated in v11. The most notable change is that these packages now require Dart Sass in order to compile as they now use Sass Modules to improve compilation times.

If you were directly importing from one of these element packages, consider importing from either @carbon/styles or @carbon/react instead. Both of these packages provide entrypoints for elements packages on top of the styles for Carbon itself.

For teams using these packages directly, you will need to update each of the elements packages you’re using to the latest version.

npm install @carbon/<package-name>@latest
Copy to clipboard

Or, with Yarn:

yarn upgrade @carbon/<package-name>@latest
Copy to clipboard

Afterwards, you will need to update the import paths and import names themselves that you bring in. In general, each package now supports importing from the package directly and all carbon-- prefixed variables, mixins, and functions have been renamed to remove the prefix.

For full details fo the changes to each elements package, check out the links below.

Package	Migration Docs
`@carbon/colors`	Link
`@carbon/elements`	Link
`@carbon/grid`	Link
`@carbon/layout`	Link
`@carbon/motion`	Link
`@carbon/themes`	Link
`@carbon/type`	Link

If you were previously using the @carbon/import-once package, you can continue to use this in v11. However, this package will receive no further updates after Carbon switched to using Sass Modules.

Edit this page on GitHub

Guide: Design

Migrating: FAQs

Guide

Overview

carbon-components-react

Step 1: Install @carbon/react

Step 2: Styles and Dart Sass

Step 3: Setup Dart Sass for your project

Step 4: Update style import paths

Step 5: Update Sass imports

Step 6: Update JavaScript imports

Step 7: Update icon imports

Step 8: Update components that have changed

Changes to className

Changes to size

Notification

Update ToastNotification usage

Update InlineNotification usage

When using ActionableNotification:

Tabs

Update Tabs and Tab usage

Step 9: Done with @carbon/react!

carbon-components

Step 1: Install @carbon/styles

Step 2: Install Dart Sass

Step 3: Setup Dart Sass

Step 4: Update import paths

Step 5: Update imports

Step 6: Update bx to cds

Step 7: Enable flexbox grid

Step 8: Update color tokens

Step 9: Done with @carbon/styles!

@carbon/icons-react

Changes to size

Removed icons

Migration

Manual migration

carbon-icons

Elements

Changes to `className`

Changes to `size`

Update `ToastNotification` usage

Update `InlineNotification` usage

When using `ActionableNotification`:

Update `Tabs` and `Tab` usage