Guide

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

Or, with Yarn:

Now that you’ve removed the old packages and brought in the new ones, run the codemod below to fix your pathing.

After running the command, your code should start looking like this:

Step 2: Install Dart Sass

If you were previously 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.

First, let’s remove node-sass from your project. If you don’t have node-sass, no worries, just skip down and begin adding sass.

Or, with Yarn:

Now, let’s install sass:

Or, with Yarn:

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 3: Update style import paths

Now, open your project’s root stylesheet to make the following changes:

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

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

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

For cases where your projects does’t need to include everything via @use '@carbon/react'; and just want to do individual component styles.

When migrating your custom components, some of our most used sass assets are included below, along with what you would need to have at the top of your file to use it. Essentially, all we are doing is including the path where we would find these styles in our package.

Now that you’ve migrated all of your imports, do a find/replace using your favorite code editor. The prefix carbon-- is no longer necessary. You can do a find for carbon-- and replace it with nothing to remove across all your files like the example below. The full list of changes are available in our Migration Docs.

Once you’ve removed the prefix, your styles should all be set using the old, v10 tokens. We recommend teams install the community supported stylelint-plugin-carbon-tokens to further assist in migrating your tokens to v11 tokens as the old v10 tokens will be removed in our next major release.

Step 4: Updating component size props

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:

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

Run the following codemods to update the size prop across the effected components in your project.

By running the series of codemods, they will do the following, in order:

1. Removes the deprecated small boolean prop and replaces it with size="sm".
2. Removes v10 size props and replaces them with v11 sizes props.

It’s important to run the npx commands in the order that they are presented above. Doing them out of order might result in the codemod not working as intended.

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 listed above. The codemod will make short work of these changes.

• 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

Step 5: Update icon sizes and imports

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.

Run the following codemods to update your project’s icons.

By running the series of codemods, they will do the following, in order:

1. Removes the size from the import and places it on the icon directly.
2. Remove the @carbon/icons-react pathing and replace it with @carbon/react/icons.

It’s important to run the npx commands in the order that they are presented above. Doing them out of order might result in the codemod not working as intended.

After running the command, instead of your icons imports looking like this:

Step 6: 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
• 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.

Step 7: 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.

Step 1: Install @carbon/styles

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

Or, with Yarn:

Next, install the @carbon/styles package:

Or, with Yarn:

Step 2: Install and configure 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:

Or, with Yarn:

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.

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 3: Update import paths and tokens

Now, open your project’s root stylesheet to make the following changes:

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

For cases where your projects does’t need to include everything via @use '@carbon/styles'; and just want to do individual component styles.

When migrating your custom components, some of our most used sass assets are included below, along with what you would need to have at the top of your file to use it. Essentially, all we are doing is including the path where we would find these styles in our package.

Now that you’ve migrated all of your imports, do a find/replace using your favorite code editor. The prefixcarbon-- is no longer necessary. You can do a find for carbon-- and replace it with nothing to remove across all your files like the example below. The full list of changes are available in our Migration Docs.

Once you’ve removed the prefix, your styles should all be set using the old, v10 tokens. We recommend teams install the community supported stylelint-plugin-carbon-tokens to further assist in migrating your tokens to v11 tokens as the old v10 tokens will be removed in our next major release.

Step 4: 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:

Step 5: 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:

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 6: 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.