Guide

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:

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.

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.

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

Or, with Yarn:

Next, install the @carbon/react package:

Or, with Yarn:

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:

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.

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.

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.