Skip to main contentCarbon Design System

Guide

Here you can find information on how to migrate your code from Carbon v10 to v11. As with any major version, there are some exciting features we’re looking forward to sharing with you. We hope to make your transition as smooth as possible by detailing all of the updates below.

Changelog

Feature
Status
MigratePackages or components impacted
@carbon/react
Breaking
Components@carbon/react carbon-icons carbon-components
@carbon/styles
Breaking
Stylescarbon-components @carbon/react carbon-components-angular carbon-components-vue
Color Tokens
Breaking
Color tokensAll components
CSS Grid
Breaking
CSS Grid@carbon/react @carbon/grid
Component size prop
Breaking
CSS Grid@carbon/react components that have different size variations
Icons size prop
Breaking
Icons size prop@carbon/react/icons @carbon/icons-react All icons
Component className prop
Breaking
CSS Grid@carbon/react
Event handlers
Breaking
CSS Grid@carbon/react
Notifications
Breaking
Notifications@carbon/react
Tooltip
Breaking
CSS Grid@carbon/react
ContentSwitcher
Breaking
CSS Grid@carbon/react
Layer Component
Breaking
LayeringComponents using light prop
Theme Component
New
Theming
Popover
New
New components@carbon/react carbon-components
ToggleTip
New
New components@carbon/react carbon-components
Dialog
New
New components@carbon/react carbon-components
carbon-icons
Deprecated
Components
carbon-components
Deprecated
Styles
@carbon/react
Deprecated
Components

Components
Breaking

We have deprecated @carbon/react, carbon-icons and carbon-components in favor of our new package @carbon/react. All of the component usage and API remains the same. The big change with this is to avoid having to install three separate packages that you have to keep in sync.

What this means for you and your team

Going forward, using our components and styles will be as easy as just installing or updating one package.

How to migrate

  1. Install the new package
npm i @carbon/react
yarn add @carbon/react
  1. Remove the old packages
npm uninstall carbon-components @carbon/react carbon-icons
yarn remove carbon-components @carbon/react carbon-icons
  1. Update package imports. Migration for this can be as easy as find-and-replace. Search for anywhere you’re importing components or icons and update the import to point to @carbon/react. Read the next section below to find out how to migrate styles.
import { Button } from '@carbon/react';
function MyComponent() {
return <Button>Example usage</Button>;
}
import { Add16 } from '@carbon/react/icons';
function MyComponent() {
return <Add16 />;
}

Resources

Styles
Breaking

In v11, our Carbon styles feature two essential changes: their own dedicated package, @carbon/styles, and transitioning to Sass modules. If you’re using our React components we have some great news for you, you don’t have to install the styles package! @carbon/react already forwards all the sass included in @carbon/styles. If you are a library not using our React components, and just consuming our styles, then your migration will require installing the new package in addition to what’s listed below.

Using Dart-Sass, we are finally able to use the Module System, dropping the import-once helpers that have being causing awful compilation and build times, and re-thinking how developers bring styles into Carbon.

Here are some reasons why we’re moving away from Node-Sass and moving towards Dart-Sass:

  • Import Once: To offer better flexibility for importing Sass files, the project used a convention to offer style deduplication due to Sass’s @import behavior.
  • Long compile times: While this technique would compile fine using Sass CLIs directly, tooling like sass-loader would take an increasingly large amount of time.
  • Incorrect behavior: In certain configurations with Webpack <4 and sass-loader, style duplication was not even being prevented.
  • LibSass deprecation: When LibSass was deprecated, and subsequently node-sass, we knew it was time to start looking towards Dart Sass.

What this means for you and your team

  • Faster compile times
  • Faster build times
  • Over-all more flexibility when importing styles

How to migrate

  1. Projects that are currently using webpack with sass-loader the update should be automatic.
  2. Projects using create-react-app or Next.js, remove node-sass from your dependencies and add sass as the replacement.
  3. In any of your files where you are using Carbon sass (tokens, mixins, or funcions), you will now need to import the specific sass file at the top. You will use the @use keyword instead of @import to include the Carbon sass, as seen below. If you’re using our React components, your import will point to the @carbon/react package. If you’re a library just using the styles package, your import will point to that.
@use '@carbon/react/scss/theme';
body {
background: theme.$background;
}

Alternatively, if you don’t want to deal with prefixing all the Carbon sass instances, you can do the following:

@use '@carbon/react/scss/theme' as *;
body {
background: $background;
}

To learn more about getting starting with Dart Sass, usage, and importing specific Carbon sass, checkout our styles docs or read about it from a developer’s perspective in this Medium article. Checkout a live example of mixins and design tokens using the Carbon tutorial.

Resources

Color Tokens
Breaking

We have renamed our color tokens to be more semantic and better inform on their usage. Some of the changes can be easily done with find-and-replace, however, some may require more manual updates. When migrating, make sure to double check that you were using the correct v10 token as to not migrate to an incorrect token.

What this means for you and your team

  • Intuitive naming ensures correct token usage
  • Less ambiguity around what a color token is for

How to migrate

  1. Check for any sass files that are referencing color tokens, and use our color token migration table to find the updated token name. We recommend checking manually since some of the v10 tokens apply to more than one v11 token, depending on its usage. For example, hover-ui could be field-hover or layer-hover.

To view a full table of v10 color tokens and their v11 equivalent, check out our colors migration doc.

Resources

CSS Grid
Breaking

A huge change for us this release is dropping support for IE11, which means we can now support CSS Grid. 🎉 Previously, our grid used CSS Flexbox, which made it hard to support nesting grids. At the moment, we are not providing an option to continue using flexbox grid in v11. Another notable change is that, by default, our grid is now 16 columns and there is no continued support for 12 columns.

What this means for you and your team:

  • 16 column grid only
  • Support for nested grids

How to migrate

Grid and Column continue to have the same props, but operate just a little bit differently. We realize the strategy for updating the grid might change from team to team, so instead we’re just going to highlight some of the big changes you need to keep in mind when tackling this transition.

  • If you are using a 3 column layout anywhere, we suggest talking to your design team to decide on an alternate layout since we are no longer supporting 12 columns. We realize this may be frustrating, but we hope the other cool features we now support make it worth the change!
  • Use Grid component for subgrids.
  • Row component is deprecated. You can drop Column components directly into Grid, including nested grids.
  • All columns by default will span just one column, not span the full width like flex columns. You must be explicit about how many columns you want to span for each breakpoint. Below, you can find what a full width 4 column layout would’ve looked like in v10 and what it looks like now in v11.
  • To view more detailed examples of our v11 grid, checkout our grid story.

Some usage guidelines to keep in mind when migrating are:

  • Wide grid should always be the parent grid
  • Some grids, like condensed grid, don’t exist in isolation; they are always mixed.

v10 auto columns

<Grid>
<Row>
<Column>1 of 4</Column>
<Column>1 of 4</Column>
<Column>1 of 4</Column>
<Column>1 of 4</Column>
</Row>
</Grid>

v11 auto columns

<Grid>
// first row - 4 col full span like the v10 auto columns
<Column lg={4}>1 of 4</Column>
<Column lg={4}>1 of 4</Column>
<Column lg={4}>1 of 4</Column>
<Column lg={4}>1 of 4</Column>
// second row - v11 auto columns
<Column>1 of 8</Column>
<Column>1 of 8</Column>

Nested grid

<Grid>
<Column sm={2} md={4} lg={3}>
<p>Small: Span 2 of 4</p>
<p>Medium: Span 4 of 8</p>
<p>Large: Span 3 of 16</p>
</Column>
<Column sm={2} md={4} lg={10}>
<p>Small: Span 2 of 4</p>
<p>Medium: Span 4 of 8</p>

Resources

Theming

With our theming updates we have some new features and some breaking changes. You can now specify you’re theme with our new Theme component., and incorporate inline theming. You can also specify a layer with a Layer component.

Layer Component
Breaking

In regards to theming, we have also added in a new Layer component. The Layer component replaces the light prop. It is a container that renders the cds--layer class name. The class name then remaps contextual tokens to the next layer. This allows you to style different layers, or directly use the tokens exported from our styles package.

What this means for you and your team

  • Layer componet replaces light prop. See the first example below.
  • More flexibility for 3 layer stacking vs. 2 layer stacking
  • Third layer stacking will now be supported in dark themes
// v10
<Dropdown light />
// v11
<Layer>
<Dropdown />
</Layer>

Here is an example of how you can use the Layer component:

<Layer>
<ChildComponent />
<Layer>
<ChildComponent />
<Layer>
<ChildComponent />
</Layer>
</Layer>
</Layer>

To learn more about how our Layer component works and it’s API, checkout out the resource link below.

Theme Component
New

We have added a new, flexible Theme component. The Theme component allows you to specify the theme for a section of the page, for example with inline theming, or render a theme for an entire page.

What this means for you and your team

  • Inline theming 🎉

Here is an example of how you can use the Theme component:

<Theme theme="g90">
<ChildComponent />
</Theme>

To learn more about how our Theme component works with our useTheme hook, checkout our usage docs. You can also checkout a live example of the Carbon Tutorial to see theming in action.

Resources

Updates to @carbon/icons-react

We have two new changes to our @carbon/icons-react package. We have updated the default prop size and the way it can be imported.

Icon size prop

We are updating the default size prop for all icons to md.

Importing

All icons can now be imported from @carbon/react/icons. In v11, you’ll still be able to access @carbon/icons-react, however it is available directly from the @carbon/react package, by default.

Here is an example of how to import an icon:

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

Component API

Size prop updates
Breaking

We updated all our components with size variants to have the same API. Previously, the size options were inconsistent: field, medium, short. Sizing options will now be the same across all components for less confusion.

What this means for you and your team

  • You will always know what to expect from components to size correctly

How to migrate

The following components all have size variants that may be affected in your code:

  • 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

If you are using any size variants of those listed components, use the following table to determine what updated value to use for the size prop. The default size in v11 is md (40px).

Prop valueSize
xs24px
sm32px
md40px
lg48px
xl64px
2xl80px

ClassName prop updates
Breaking

We updated our components to pass custom className to the outermost element of a component’s inner markup. A lot of components already placed this prop on the outermost layer, but many were targetting elements inside the wrappers.

What this means for you and your team

  • Easily target any component HTML element since the className is now added to the wrapper

How to migrate

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 in the wrapper.

  • 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

Event handler updates
Breaking

Guidance coming soon.

New Components

We are releasing a few new components that complement our accessibility initiatives and component changes.

Popover

This component primitive is most similar a tile or card. However, Popover is a primitive consumed by other components to render content. Popover components can also be referred to as Disclosures, and will be accomodate a lot of the changes being made in our Tooltip component.

Learn more about our Popover component and it’s API below:

Notifications
Breaking

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.

What this means for you and your team

  • Notifications will be WAI-ARIA compliant out of the box without the explicit need for additional functionality or configuration

How to migrate

Update ToastNotification usage

  • The title, subtitle and caption props have been removed. Compose notification contents using children instead.
  • 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 title, subtitle props have been removed. Compose notification contents using children instead.
  • 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.

Resources