Guide

• Changelog
• Components
• Styles
• Color Tokens
• CSS Grid
• Layering
• Theming

Changelog

Components

Breaking

What this means for you and your team

How to migrate

1. Install the new package

npm i @carbon/react
Copy to clipboardCopied!

yarn add @carbon/react
Copy to clipboardCopied!

2. Remove the old packages

npm uninstall carbon-components carbon-components-react carbon-icons
Copy to clipboardCopied!

yarn remove carbon-components carbon-components-react carbon-icons
Copy to clipboardCopied!

3. 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>;
}
Copy to clipboardCopied!

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

function MyComponent() {
  return <Add16 />;
}
Copy to clipboardCopied!

Resources

Styles

Breaking

• 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;
}
Copy to clipboardCopied!

@use '@carbon/react/scss/theme' as *;

body {
  background: $background;
}
Copy to clipboardCopied!

Resources

@carbon/styles docs

Migrating from node-sass to dart-sass

One quick way to get ready for Carbon v11

Discover mixins using the Carbon tutorial

Color Tokens

Breaking

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.

Resources

CSS Grid

Breaking

What this means for you and your team:

• 16 column grid only
• Support for nested grids

How to migrate

• 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.

• 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>
Copy to clipboardCopied!

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>
Copy to clipboardCopied!

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>
Copy to clipboardCopied!

Resources

CSS Grid docs

CSS Grid storybook

Theming

Layer Component

Breaking

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>
Copy to clipboardCopied!

<Layer>
  <ChildComponent />
  <Layer>
    <ChildComponent />
    <Layer>
      <ChildComponent />
    </Layer>
  </Layer>
</Layer>
Copy to clipboardCopied!

Theme Component

New

What this means for you and your team

• Inline theming 🎉

<Theme theme="g90">
  <ChildComponent />
</Theme>
Copy to clipboardCopied!

Resources

Updates to @carbon/icons-react

Icon size prop

Importing

import { Add } from '@carbon/react/icons';
Copy to clipboardCopied!

Component API

Size prop updates

Breaking

What this means for you and your team

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

How to migrate

• 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

ClassName prop updates

Breaking

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

• 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

New Components

Popover

Notifications

Breaking

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

Notification usage examples

Notification accessibility page