Skip to main contentCarbon Design System

Guide

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

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](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade)

carbon-components-react

Starting in v11, the React components for Carbon live in the @carbon/react package. Alternatively, you can continue to use carbon-components as it re-exports components from 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

Or, with Yarn:

yarn remove carbon-components carbon-components-react carbon-icons @carbon/icons-react

Next, install the @carbon/react package:

npm install @carbon/react

Or, with Yarn:

yarn add @carbon/react

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

Or, with Yarn:

yarn add sass

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';

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';

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';

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);

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';

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 you’re 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](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade)

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';

Step 7: Update icon imports

This step can be automated using the `@carbon/upgrade` CLI. For full details, see the `@carbon/upgrade` [package documentation](https://github.com/carbon-design-system/carbon/tree/main/packages/upgrade)

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 />

After

import { Add } from '@carbon/react/icons';
function MyComponent() {
return (
<>
<Add size={32} />
<Add size={24} />
<Add size={20} />
<Add />

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

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

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 valueSize
xs24px
sm32px
md40px
lg48px
xl64px
2xl80px

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

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>

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>

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

Or, with Yarn:

yarn remove carbon-components

Next, install the @carbon/styles package:

npm install @carbon/styles

Or, with Yarn:

yarn add @carbon/styles

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

Or, with Yarn:

yarn add sass

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

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.

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 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';

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';

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';

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);

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/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';

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.

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');

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';

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);

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.

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.

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/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

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 />

After

import { Add } from '@carbon/icons-react';
function MyComponent() {
return (
<>
<Add size={32} />
<Add size={24} />
<Add size={20} />
<Add />

Removed icons

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

Assetv10v11
app-switcherAppSwitcherSwitcher
arrowsArrowsArrowsVertical
back-to-topBackToTopUpToTop
checkbox—undeterminateCheckboxUndeterminateCheckboxIndeterminate
checkbox—undeterminate—filledCheckboxUndeterminateFilledCheckboxIndeterminateFilled
cloud—lightningCloudLightningRemoved
cloud—rainCloudRainRemoved
cloud—snowCloudSnowRemoved
deleteDeleteTrashCan
edit-filterEditFilterFilterEdit
sunnySunnyRemoved
research—bloch-sphereResearchBlockSphereBlochSphere
research—hinton-plotResearchHintonPlotHintonPlot
research—matrixResearchMatrixMatrix
misuse—altMisuseAltMisuseOutline
logo—googleLogoGoogleRemoved
mammogram—stackedMammogramStackedRemoved
logo—deliciousLogoDeliciousRemoved
logo—stumbleuponLogoStumbleUponRemoved
letter—Aa—largeLetterAaLargeTextFont
glyph—caution-invertedGlyphCautionInvertedCautionInverted
glyph—cautionGlyphCautionCaution
glyph—circle-fillGlyphCircleFillCircleFill
glyph—circle-strokeGlyphCircleStrokeCircleStroke
glyph—criticalGlyphCriticalCritical
glyph—incompleteGlyphIncompleteIncomplete
glyph—square-fillGlyphSquareFillSquareFill
glyph—undefinedGlyphUndefinedUndefined

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:

PackageFrameworkLink
@carbon/icons-reactReactLink
@carbon/icons-angularAngularLink
@carbon/icons-vueVueLink
carbon-icons-svelteSvelteLink
@carbon/iconsVanilla JavaScriptLink

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

Or, with Yarn:

yarn upgrade @carbon/<package-name>@latest

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.

PackageMigration Docs
@carbon/colorsLink
@carbon/elementsLink
@carbon/gridLink
@carbon/layoutLink
@carbon/motionLink
@carbon/themesLink
@carbon/typeLink

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.