Guide

This guide helps you update your project to Carbon v11. This guide 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 previously were using the following packages:

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.

For a full list of changes, checkout our Migration Docs.

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.

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.

Note: 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

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

Or, with Yarn:

Next, install the @carbon/styles package:

Or, with Yarn:

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 due to our migration over 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.

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

Or, you imported the styles through specific entrypoints:

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

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.

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.

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

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.

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:

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.

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:

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.

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, pleasefeel 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.

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:

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

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.

Or, with Yarn:

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.

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.