This document outlines all of the changes to the Carbon Design System from v10 to v11. If you're just getting started, check out our migration site.
If you're looking for migration information for a specific package, use the list of packages below.
- carbon-components
- carbon-components-react
- carbon-icons
- @carbon/icons
- @carbon/icons-react
- @carbon/colors
- @carbon/elements
- @carbon/grid
- @carbon/layout
- @carbon/motion
- @carbon/themes
- @carbon/type
Carbon also provides codemods through the
@carbon/upgrade
package to help with
migration.
In v10, the carbon-components
package ships Sass styles and Vanilla JavaScript
for components in our Design System. Starting in v11, we will split out our
styles into a dedicated package: @carbon/styles
. In addition, we will no
longer support the Vanilla JavaScript for our components.
Along with this change, the styles of Carbon have been completely updated to use
Sass Modules. This change
requires that teams use the Dart Sass package.
Support for node-sass
has been dropped starting in v11.
This decision was made after seeing the deprecation notice of LibSass in late 2020.
With this change to Sass Modules, you'll find that many of the ways that you are
using Carbon today have been updated and streamlined. In general, most paths
have changed from the long form scss/globals/scss/path/to/file
to
scss/path/to/file
.
For example, to access the theme
entrypoint you would have needed to import
scss/globals/scss/theme
in v10. Now, this entrypoint lives at scss/theme
.
Alongside the updates to filepaths, you will find that helper mixins, functions,
and variables have been updated to no longer have a carbon--
prefix. With Sass
Modules, the module name now serves as an appropriate prefix and provides
scoping for variables, mixins, and functions. By performing a basic find and
replace operation, the prefix carbon--
can be easily removed, as illustrated
in the following example.
- @include carbon--breakpoint(lg) {
+ @include breakpoint(lg) {
width: 42%;
}
There are two major areas of changes in the package, namely:
The majority of the files currently available under /scss/globals/scss
are now
available directly under the scss
directory, or through our new utilities
folder in scss/utilities
.
Below, you'll find an overview of files that are a part of our Public API and where they have moved to in v11. Each row also contains a link to a section below that goes over any API changes for the file.
File | v11 |
---|---|
scss/globals/scss/styles.scss |
Moved to index.scss in @carbon/styles |
scss/globals/grid/_grid.scss |
Moved to scss/_grid.scss |
scss/globals/scss/_colors.scss |
Moved to scss/_colors.scss |
scss/globals/scss/_css--body.scss |
Removed, most of these styles are available through the CSS reset |
scss/globals/scss/_css--font-face.scss |
Moved to scss/fonts |
scss/globals/scss/_css--helpers.scss |
Moved to scss/utilities/ |
scss/globals/scss/_css--reset.scss |
Moved to scss/_reset.scss |
scss/globals/scss/_helper-classes.scss |
Moved to scss/utilities/ |
scss/globals/scss/_helper-mixins.scss |
Moved to scss/utilities/ |
scss/globals/scss/_import-once.scss |
Removed |
scss/globals/scss/_layer.scss |
Removed |
scss/globals/scss/_layout.scss |
This file has been split into scss/spacing and scss/utilities/z-index |
scss/globals/scss/_mixins.scss |
Removed, import mixins directly from appropriate file |
scss/globals/scss/_motion.scss |
Moved to scss/_motion.scss |
scss/globals/scss/_spacing.scss |
Moved to scss/_spacing.scss |
scss/globals/scss/_theme-tokens.scss |
Moved to scss/_themes.scss |
scss/globals/scss/_theme.scss |
Moved to scss/_theme.scss |
scss/globals/scss/_typography.scss |
Moved to scss/_type.scss |
scss/globals/scss/_vars.scss |
Removed, import variables directly from appropriate file |
scss/globals/scss/vendor/* |
These files are now re-exported from the top-level scss folder |
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/scss/styles.scss'; |
@use '@carbon/styles'; |
(alias) | @use '@carbon/react'; |
The styles.scss
entrypoint was provided as a way to bring in all of the styles
for the Carbon Design System. In v11, this is available through
@carbon/styles/index.scss
which can be directly imported with @use
by
writing out:
@use '@carbon/styles';
If you are overriding different settings of the project, like $prefix
, you
will need to pass those into the with
block in the import:
@use '@carbon/styles' with (
$prefix: 'cds'
);
While the preference is to import files using @use
, you may also use @import
to bring in styles.
For a full overview of changes to how you configure Carbon, checkout our configuration section below.
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/scss/colors'; |
@use '@carbon/styles/scss/colors'; |
@use '@carbon/react/scss/colors'; |
The scss/globals/scss/_colors.scss
entrypoint provided a re-export of the
@carbon/colors
package. This entrypoint now lives at scss/_colors.scss
in
@carbon/styles
and can be included by writing:
@use '@carbon/styles/scss/colors';
.example {
color: colors.$blue-50;
}
The following is a list of API changes in v11 for @carbon/colors
that are
present in @carbon/styles/scss/colors
:
v10 | v11 |
---|---|
$ibm-* variables |
Removed |
$carbon-* variables |
Removed |
$ibm-color-map |
Removed |
$carbon--colors |
Removed, replaced by $colors |
@mixin ibm--colors |
Removed |
@mixin carbon--colors |
Removed |
In v11, we support a broad range of font families from IBM Plex through the
@ibm/plex
package. By default, these font families are loaded through the
@ibm/plex
package and require a bundler that supports loading in font files in
this way.
You can still configure Carbon to pull in these fonts through a CDN with the
$use-akamai-cdn
flag available in scss/_config.scss
.
IBM Plex Sans, IBM Plex Mono, and IBM Plex Serif are all loaded in automatically
with the light, normal, and medium font weights. You can configure the
scss/fonts
import to include additional font families and font weights.
For more information, check out the documentation.
The scss/globals/scss/_css--helpers
entrypoint provides class-based helpers
when the $css--helpers
flag is set to true, specifically:
bx--assistive-text
andbx--visually-hidden
bx--body
In v11, the assistive text and visually hidden classes are now available under:
scss/utilities/_visually-hidden
.
The bx--body
class has been removed.
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/scss/css--reset'; |
@use '@carbon/styles/scss/reset'; |
@use '@carbon/react/scss/reset'; |
The scss/globals/scss/css--reset
entrypoint is used for including a CSS reset
in a project using Carbon. It is configurable using the $css--reset
global
flag.
In v11, this entrypoint is now available at scss/reset
and is still
configurable with the $css--reset
configuration option. By default,
$css--reset
is set to true
.
The scss/globals/scss/_helper-classes.scss
entrypoint was used to emit CSS
classes for text truncation, specifically:
bx--text-truncate--end
bx--text-truncate--front
These classes are are now available under scss/utilities/text-truncate
.
The scss/globals/scss/_helper-mixins.scss
entrypoint exported a number of
helper mixins that could be used when building components. In v11, these helpers
have been moved to utilities located under scss/utilities/
. Below is a table
that details to which files a particular helper has been moved.
v10 | v11 |
---|---|
@mixin text-overflow |
scss/utilities/_text-overflow.scss |
@mixin placeholder-colors |
scss/utilities/_placeholder-colors.scss |
@mixin box-shadow |
scss/utilities/_box-shadow.scss |
@mixin focus-outline |
scss/utilities/_focus-outline.scss |
@mixin rotate |
scss/utilities/_rotate.scss |
@mixin hidden |
scss/utilities/_visually-hidden.scss |
@mixin button-reset |
scss/utilities/_button-reset.scss |
@mixin skeleton |
scss/utilities/_skeleton.scss |
@keyframes skeleton |
scss/utilities/_keyframes.scss |
@mixin high-contrast-mode |
scss/utilities/_high-contrast-mode.scss |
This entrypoint has been split into two files. For anything related to spacing
or layout, you can use the scss/spacing
entrypoint directly. For anything
related to z-index you can use scss/utilities/z-index
directly.
The scss/globals/scss/_mixins.scss
entrypoint re-exported mixins from the
following files:
scss/globals/scss/helper-mixins
scss/components/button/mixins
;scss/components/loading/mixins
;scss/components/notification/mixins
;scss/components/tag/mixins
;scss/components/structured-list/mixins
;
In v11, this entrypoint has been removed. If you are using a mixin from this entrypoint, find the appropriate mixin from the migration guidance for one of the files above.
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/scss/motion'; |
@use '@carbon/styles/scss/motion'; |
@use '@carbon/react/scss/motion'; |
The scss/globals/scss/_motion.scss
entrypoint re-exported exports from the
@carbon/motion
package along with providing a number of helpers and variables
for duration and easing curves.
v10 | v11 |
---|---|
$carbon--ease-in |
Renamed to $ease-in |
$carbon--ease-out |
Renamed to $ease-out |
$carbon--standard-easing |
Renamed to $standard-easing |
$transition--base |
Renamed to $transition-base |
$transition--expansion |
Renamed to $transition-expansion |
$duration--fast-01 |
$duration-fast-01 |
$duration--fast-02 |
$duartion-fast-02 |
$duration--moderate-01 |
$duration-moderate-01 |
$duration--moderate-02 |
$duration-moderate-01 |
$duration--slow-01 |
$duration-slow-01 |
$duration--slow-02 |
$duration-slow-02 |
@function motion |
No changes |
@mixin motion |
No changes |
For a full overview of what is available in this entrypoint, check out the
API documentation for the
@carbon/motion
package.
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/scss/spacing'; |
@use '@carbon/styles/scss/spacing'; |
The scss/globals/scss/_spacing.scss
entrypoint provided a number of variables
for spacing and include re-exports from the @carbon/layout
package for
mini-unit
support as well as the spacing scale.
In v11, this entrypoint has been moved to scss/_spacing.scss
and a number of
exports have been changed.
v10 | v11 |
---|---|
$spacing-01 |
No changes |
$spacing-02 |
No changes |
$spacing-03 |
No changes |
$spacing-04 |
No changes |
$spacing-05 |
No changes |
$spacing-06 |
No changes |
$spacing-07 |
No changes |
$spacing-08 |
No changes |
$spacing-09 |
No changes |
$spacing-10 |
No changes |
$spacing-11 |
No changes |
$spacing-12 |
No changes |
$spacing-13 |
No changes |
$carbon--spacing |
Renamed to $spacing |
$carbon--spacing-01 |
Removed, replaced with $spacing-01 |
$carbon--spacing-02 |
Removed, replaced with $spacing-02 |
$carbon--spacing-03 |
Removed, replaced with $spacing-03 |
$carbon--spacing-04 |
Removed, replaced with $spacing-04 |
$carbon--spacing-05 |
Removed, replaced with $spacing-05 |
$carbon--spacing-06 |
Removed, replaced with $spacing-06 |
$carbon--spacing-07 |
Removed, replaced with $spacing-07 |
$carbon--spacing-08 |
Removed, replaced with $spacing-08 |
$carbon--spacing-09 |
Removed, replaced with $spacing-09 |
$carbon--spacing-10 |
Removed, replaced with $spacing-10 |
$carbon--spacing-11 |
Removed, replaced with $spacing-11 |
$carbon--spacing-12 |
Removed, replaced with $spacing-12 |
$carbon--spacing-13 |
Removed, replaced with $spacing-13 |
$spacing-baseline |
Removed |
$spacing-4xs |
Removed |
$spacing-3xs |
Removed |
$spacing-2xs |
Removed |
$spacing-xs |
Removed |
$spacing-sm |
Removed |
$spacing-md |
Removed |
$spacing-lg |
Removed |
$spacing-xl |
Removed |
$spacing-2xl |
Removed |
$spacing-3xl |
Removed |
$carbon--layout-01 |
Removed, replaced by $spacing-05 |
$carbon--layout-02 |
Removed, replaced by $spacing-06 |
$carbon--layout-03 |
Removed, replaced by $spacing-07 |
$carbon--layout-04 |
Removed, replaced by $spacing-09 |
$carbon--layout-05 |
Removed, replaced by $spacing-10 |
$carbon--layout-06 |
Removed, replaced by $spacing-12 |
$carbon--layout-07 |
Removed, replaced by $spacing-13 |
$layout-01 |
Removed, replaced by $spacing-05 |
$layout-02 |
Removed, replaced by $spacing-06 |
$layout-03 |
Removed, replaced by $spacing-07 |
$layout-04 |
Removed, replaced by $spacing-09 |
$layout-05 |
Removed, replaced by $spacing-10 |
$layout-06 |
Removed, replaced by $spacing-12 |
$layout-07 |
Removed, replaced by $spacing-13 |
$layout-2xs |
Removed |
$layout-xs |
Removed |
$layout-sm |
Removed |
$layout-md |
Removed |
$layout-lg |
Removed |
$layout-xl |
Removed |
$layout-2xl |
Removed |
$carbon--layout |
Removed |
$carbon--mini-unit-size |
Removed |
@function carbon--mini-units |
Removed |
For a full overview of what is available in this entrypoint, check out the
API documentation for the
@carbon/layout
package.
The scss/globals/scss/_theme-tokens.scss
entrypoint provides several component
tokens along with re-exports from @carbon/themes
package.
v10 | v11 |
---|---|
Design tokens | Available in scss/_theme.scss |
$focus |
Available directly in the theme |
$inverse-focus-ui |
Available directly in the theme |
$accordion-flex-direction |
Moved to scss/components/accordion |
$accordion-justify-content |
Moved to scss/components/accordion |
$accordion-arrow-margin |
Moved to scss/components/accordion |
$accordion-title-margin |
Moved to scss/components/accordion |
$accordion-content-padding |
Moved to scss/components/accordion |
$button-font-weight |
Moved to scss/components/button |
$button-font-size |
Moved to scss/components/button |
$button-border-radius |
Moved to scss/components/button |
$button-height |
Moved to scss/components/button |
$button-padding |
Moved to scss/components/button |
$button-padding-field |
Moved to scss/components/button |
$button-padding-sm |
Moved to scss/components/button |
$button-padding-lg |
Moved to scss/components/button |
$button-padding-ghost |
Moved to scss/components/button |
$button-padding-ghost-field |
Moved to scss/components/button |
$button-padding-ghost-sm |
Moved to scss/components/button |
$button-border-width |
Moved to scss/components/button |
$button-outline-width |
Moved to scss/components/button |
$button-outline-offset |
Moved to scss/components/button |
$button-outline |
Moved to scss/components/button |
$copy-active |
Moved to scss/components/code-snippet |
$copy-btn-feedback |
Moved to scss/components/code-snippet |
$checkbox-border-width |
Moved to scss/components/checkbox |
$content-switcher-border-radius |
Moved to scss/components/content-switcher |
$content-switcher-option-border |
Moved to scss/components/content-switcher |
$content-switcher-divider |
Moved to scss/components/content-switcher |
$data-table-heading-transform |
Moved to scss/components/data-table |
$data-table-heading-border-bottom |
Moved to scss/components/data-table |
$data-table-row-height |
Moved to scss/components/data-table |
$data-table-zebra-color |
Moved to scss/components/data-table |
$data-table-column-hover |
Moved to scss/components/data-table |
$date-picker-in-range-background-color |
Moved to scss/components/data-table |
$input-border |
Removed |
$input-label-weight |
Moved to scss/components/form |
$link-visited |
Moved to scss/components/link |
$link-inverse-color |
Moved to scss/components/link |
$modal-border-top |
Moved to scss/components/modal |
$modal-footer-background-color |
Moved to scss/components/modal |
$notification-info-background-color |
Moved to scss/components/notification |
$notification-error-background-color |
Moved to scss/components/notification |
$notification-warning-background-color |
Moved to scss/components/notification |
$notification-success-background-color |
Moved to scss/components/notification |
$progress-indicator-bar-width |
Moved to scss/components/progress-indicator |
$progress-indicator-stroke-width |
Moved to scss/components/progress-indicator |
$progress-indicator-line-offset |
Moved to scss/components/progress-indicator |
$snippet-background-color |
Moved to scss/components/code-snippet |
$snippet-border-color |
Moved to scss/components/code-snippet |
$radio-border-width |
Moved to scss/components/radio-button |
$structured-list-padding |
Moved to scss/components/structured-list |
$structured-list-text-transform |
Moved to scss/components/structured-list |
$tab-underline-color |
Moved to scss/components/tabs |
$tab-underline-color-hover |
Moved to scss/components/tabs |
$tab-text-disabled |
Moved to scss/components/tabs |
$tab-underline-disabled |
Moved to scss/components/tabs |
$tooltip-background-color |
Moved to scss/components/tooltip |
$skeleton |
Removed, available as a token in the theme |
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/scss/theme'; |
@use '@carbon/styles/scss/theme'; |
@use '@carbon/react/scss/theme'; |
The scss/globals/scss/_theme.scss
entrypoint re-exported tokens from the
_theme-tokens.scss
entrypoint. In v11, you can import this file directly and
reference the current theme, tokens defined in the theme, as well as dynamically
retrieve the current value of a token.
@use '@carbon/styles/scss/theme';
.example {
background: theme.$background;
color: theme.$text-primary;
}
For a full overview of what is available in this entrypoint, check out our API documentation.
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/scss/typography'; |
@use '@carbon/styles/scss/type'; |
@use '@carbon/react/scss/type'; |
The scss/globals/scss/_typography.scss
entrypoint provides access to a number
of variables and helpers for working with dimensions. It also re-exports several
exports from @carbon/type
.
In v11, this entrypoint has been moved to scss/_type.scss
and several of its
exports have changed or removed.
v10 | v11 |
---|---|
$base-font-size |
Moved to scss/utilities/_convert.scss |
@function rem |
Moved to scss/utilities/_convert.scss |
@function em |
Moved to scss/utilities/_convert.scss |
$carbon--font-families |
Renamed to $font-families |
@function carbon--font-family |
Renamed to @function font-family |
@mixin carbon--font-family |
Renamed to @mixin font-family |
$carbon--font-weights |
Renamed to $font-weights |
@function carbon--font-weight |
Renamed to @function font-weight |
@mixin carbon--font-weight |
Renamed to @mixin font-weight |
For a full overview of what is available in this entrypoint, check out the
API documentation for @carbon/type
.
The scss/globals/scss/_vars.scss
entrypoint was used to access most of the
public variables from the Carbon Design System. It also specified the $prefix
used for CSS.examples in the codebase.
In v11, this file has been removed. To get access to variables that you
previously were using _vars.scss
for, you will need to find the correct direct
import. For changing the $prefix
used in the project, you can configure this
through the scss/_config.scss
entrypoint.
For more information about configuring the project, check out the configuration section below.
v10 | v11 |
---|---|
@import 'carbon-components/scss/globals/grid/grid'; |
@use '@carbon/styles/scss/grid'; |
@use '@carbon/react/scss/grid'; |
The scss/globals/grid/_grid.scss
entrypoint provides access to the flexbox
based grid from the @carbon/grid
package.
In v11, this entrypoint has been moved to scss/_grid.scss
and continues to
re-export from the @carbon/grid
package. In addition, the default grid has
been changed from the 12 column variant to the 16 column grid.
Note: if you're using $feature-flags
to set grid-columns-16
you can remove
this flag in v11
Finally, our default grid implementation no longer uses flexbox. Instead, it
uses CSS Grid. If you have existing layouts built using the flexbox grid, you
can bring in these styles through the scss/grid/flexbox
entrypoint or via the
$use-flexbox-grid
config variable.
The components located under scss/components
are available under
scss/components/<component>/_<component>.scss
. For example, to import an
accordion:
@import 'carbon-components/scss/components/accordion/accordion';
In v11, these files now live at scss/components/<component>/_index.scss
and
can be shortened to scss/components/<component>
since Dart Sass resolves
_index.scss
files automatically. for example:
// For styles
@use '@carbon/styles/scss/components/accordion';
// For React
@use '@carbon/react/scss/components/accordion';
DataTable styles are no longer all bundled into one stylesheet. To include
styles for DataTable actions, expand, skeleton, and sort you'll need to @use
each module as needed.
v10 | v11 |
---|---|
@import 'carbon-components/scss/components/data-table/data-table'; |
@use '@carbon/styles/scss/components/data-table'; |
@use '@carbon/styles/scss/components/data-table/action'; |
|
@use '@carbon/styles/scss/components/data-table/expandable'; |
|
@use '@carbon/styles/scss/components/data-table/skeleton'; |
|
@use '@carbon/styles/scss/components/data-table/sort'; |
In some situations, you may want to use or change the tokens for a specific
component. To do so you will need to configure the module and provide the tokens
you would like to see changed. For full details, see
the sass documentation for @carbon/styles
.
In v10, you could configure various aspects of Carbon using global flags that were set before including Carbon. For example, you could change the prefix used or disable the CSS reset that the project used by doing the following:
$prefix: 'cds';
$css--reset: false;
@import 'path/to/carbon';
Similarly, you could enable or disable $feature-flags
for the project with a
similar approach.
This approach no longer works with the project's switch to Sass Modules.
Instead, you will need to configure Carbon through the scss/_config.scss
entrypoint using with
. This file is re-exported in various entrypoints, so you
can configure Carbon on the main entrypoint:
@use '@carbon/styles' with (
$prefix: 'cds'
);
Or you can configure the scss/_config.scss
directly:
@use '@carbon/styles/scss/config' with (
$prefix: 'cds'
);
Note: Sass modules can only ever be configured once. Bringing in this module and configuring it should be one of the first things you do in your project.
The following is a table of configuration options and their status in v11. Ones
that are available you can configure through the scss/_config.scss
entrypoint,
ones that are removed are no longer available.
v10 | v11 |
---|---|
$css--helpers |
Removed |
$css--body |
Removed |
$css--use-layer |
Removed |
$css--reset |
No changes |
$prefix |
No changes |
$feature-flags |
Moved to scss/feature-flags |
The following files are considered internal files and have been omitted from this migration document. If you are currently using these files, please reach out for support on GitHub Discussions and we can help you migrate from the following list of files:
scss/globals/scss/_functions.scss
scss/globals/scss/_feature-flags.scss
scss/globals/scss/_deprecate.scss
scss/globals/scss/_keyframes.scss
scss/globals/scss/_tooltip.scss
scss/globals/scss/vendor/*
The carbon-components-react
package has been replaced by the @carbon/react
package in v11. While you can still use carbon-components-react
along with
v11, it has been deprecated and will stop receiving updates when v12 is
released.
In addition, this release contains updates to React components in the package. These updates include:
- Changing components from class components to functional components
- Creating consistent prop names and types across components
- Updates to make components more accessible
Some of these updates are covered by an automated codemod. View full
instructions in @carbon/upgrade
.
npx @carbon/upgrade migrate update-carbon-components-react-import-to-scoped
npx @carbon/upgrade migrate small-to-size-props
npx @carbon/upgrade migrate size-prop-updates
For a full overview of changes to components, checkout our components section below.
Component | Changes |
---|---|
Accordion |
The size prop has been updated and no longer includes xl |
AccordionItem |
View changes here |
AccordionSkeleton |
The deprecated prop uid is no longer needed and has been removed |
ActionableNotification |
View changes here |
Button |
View changes here |
ButtonSkeleton |
View changes here |
Checkbox |
View changes here |
ClickableTile |
View changes here |
Column |
View changes here |
ComboBox |
The className prop is now applied to the outermost element of ComboBox |
ComposedModal |
Updated from a class to functional component |
ContentSwitcher |
Updated from a class to functional component |
ControlledPasswordInput |
The size prop has been updated to match PasswordInput |
DatePicker |
View changes here |
DatePickerInput |
View changes here |
Dropdown |
View changes here |
DropdownSkeleton |
The deprecated prop inline has been removed |
ExpandableTile |
View changes here |
FileUploader |
View changes here |
FileUploaderButton |
View changes here |
FileUploaderItem |
The size prop has been updated to: PropTypes.oneOf(['sm', 'md', 'lg']) . Previous values such as default , field , or small are no longer supported |
FilterableMultiSelect |
View changes here |
FluidForm |
Vertical margin for form items and fieldsets is no longer included by default, use <Stack> for vertical spacing |
Form |
Vertical margin for form items and fieldsets is no longer included by default, use <Stack> for vertical spacing |
FormGroup |
View changes here |
FormLabel |
The FormLabel component no longer applies margin |
Grid |
View changes here |
HeaderMenu |
Updated from a class to functional component |
HeaderNavigation |
Updated from a class to functional component |
Icon |
Removed |
InlineLoading |
The deprecated success prop has been deprecated. Please use status="finished" instead |
InlineNotification |
View changes here |
Modal |
View changes here |
ModalFooter |
Updated from a class to functional component |
ModalHeader |
Updated from a class to functional component |
ModalWrapper |
Removed |
MultiSelect |
The className prop is now applied to the outermost element of MultiSelect |
NotificationActionButton |
View changes here |
NotificationButton |
View changes here |
NotificationTextDetails |
View changes here |
NumberInput |
View changes here |
OverflowMenu |
View changes here |
OverflowMenuItem |
View changes here |
Pagination |
Updated from a class to functional component |
PasswordInput |
The size prop has been updated to: PropTypes.oneOf(['sm', 'md', 'lg']) |
ProgressIndicator |
Updated from a class to functional component |
RadioButton |
Updated from a class to functional component |
RadioButtonGroup |
View changes here |
RadioTile |
View changes here |
Row |
View changes here |
Search |
View changes here |
SearchFilterButton |
Removed |
SearchLayoutButton |
Removed |
Select |
View changes here |
SelectableTile |
View changes here |
SideNavMenu |
Updated from a class to functional component |
Slider |
View changes here |
StructuredListBody |
Vertical margin for form items and fieldsets is no longer included by default, use <Stack> for vertical spacing |
StructuredListInput |
View changes here |
StructuredListRow |
The label prop is no longer needed and has been deprecated |
StructuredListWrapper |
The deprecated prop border has been removed |
Table |
View changes here |
TableToolbar |
The size prop has been updated to: PropTypes.oneOf(['sm', 'lg']) . Previous values such as small or normal are no longer supported |
TableToolbarSearch |
View changes here |
Tabs |
View changes here |
Tab |
View changes here |
TabContent |
View changes here |
TabsSkeleton |
View changes here |
TextArea |
The className prop is now applied to the outermost element of TextArea |
TextInput |
View changes here |
Tile |
View changes here |
TileAboveTheFoldContent |
Updated from a class to functional component |
TileBelowTheFoldContent |
Updated from a class to functional component |
TileGroup |
Updated from a class to functional component |
TimePicker |
View changes here |
TimePickerSelect |
View changes here |
ToastNotification |
View changes here |
Toggle |
View changes here |
ToggleSkeleton |
Removed |
ToggleSmall |
This component has been removed. Please use <Toggle size="sm"> instead |
ToggleSmallSkeleton |
Removed |
Toolbar |
Removed |
ToolbarDivider |
Removed |
ToolbarItem |
Removed |
ToolbarOption |
Removed |
ToolbarSearch |
Removed |
ToolbarTitle |
Removed |
Tooltip |
View changes here |
TooltipDefinition |
View changes here |
TooltipIcon |
View changes here |
- The deprecated prop
renderExpando
has been removed, userenderToggle
instead - The deprecated prop
iconDescription
is no longer needed and has been removed
- The deprecated prop
small
has been removed. Please usesize="sm"
instead - The
size
prop has been updated to:PropTypes.oneOf(['sm', 'md', 'lg', 'xl', '2xl'])
. Previous size values likedefault
,field
, orsmall
are no longer supported.
- The
size
prop has been updated to:PropTypes.oneOf(['sm', 'md', 'lg', 'xl', '2xl'])
. Previous size values likedefault
,field
, orsmall
are no longer supported.
- The deprecated prop
wrapperClassName
has been removed. UseclassName
instead. - The
onChange
prop signature has been updated. Previously, this prop would be a function of type:(boolean, string, Event) => void
. It has now been updated to pass theonChange
event as the first argument and the second argument is the state.
<Checkbox
- onChange={(checked, id, event) => {
- //
- }}
+ onChange={(event, { checked, id }) => {
+ //
+ }}
/>
- This component has been updated from a class component to a functional component
- The
className
prop is now applied to the outermost element ofDatePicker
- This component has been updated from a class component to a functional component
- The deprecated prop
iconDescription
has been removed - The deprecated prop
openCalendar
has been removed
- The
className
prop is now applied to the outermost element ofDropdown
- The deprecated prop
inline
has been removed. Please usetype="inline"
instead
- This component has been updated from a class component to a functional component
- The
iconDescription
prop is now required to label the icon
- Vertical margin is no longer included by default, use
<Stack>
for vertical spacing - The
size
prop has been updated to:PropTypes.oneOf(['sm', 'md', 'lg'])
. Previous values such asdefault
,field
, orsmall
are no longer supported
- This component has been updated from a class component to a functional component
- The
className
prop is now applied to the outermost element ofFilterableMultiSelect
- The
className
prop is now applied to the outermost element ofFormGroup
- The deprecated prop
hasMargin
has been removed. Margin for vertical spacing is no longer included, use<Stack>
for vertical spacing.
The Grid
component has been updated to use our new CSS Grid classes under the
hood. However, if you're using the Grid
component in v10 you can continue
using our flexbox-based grid with the FlexGrid
component. Similarly, Row
and
Column
will continue to work with FlexGrid
.
With the change to CSS Grid, you now will only need two components to build
layouts: Grid
and Column
. The Row
component is no longer needed.
New
- Subgrid is officially supported when using CSS Grid
Changed
- The
Grid
component now uses CSS Grid under the hood. If you would like to keep using the flexbox-based grid, useFlexGrid
instead.
The FlexGrid
component has the same API as the Grid
component in v10. You
can build layouts using FlexGrid
, Row
, and Column
. You can also keep
existing layouts that you've already built using this component.
This component has not changed between v10 and v11. However, it is no longer
needed when building layouts with Grid
. Instead, you can use Grid
and
Column
directly.
The Column
component has specific additions to work with CSS Grid. It
maintains backwards compatibility with v10. The biggest change between v10 and
v11 is that Columns
no longer will auto-span. Instead, each Column
will span
1 column in the grid unless otherwise specified.
There are also changes to how offset
works in v11. While you can continue to
use offset
in each breakpoint prop, you can now use start
and end
, as
well. These correspond to grid-column-start
and grid-column-end
,
respectively.
View the docs for the Column
component to learn more.
- This component has been updated from a class component to a functional component
- The deprecated prop
focusTrap
has been removed, this is now enabled by default - The deprecated prop
hasForm
has been removed, this is now enabled by default - The deprecated prop
iconDescription
is no longer needed and has been removed
The notification components have been updated 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.
Vertical margin is no longer included by default, use <Stack>
for vertical
spacing.
ToastNotification
updates:
children
can no longer contain interactive elements. AToastNotification
containing an action or interactive children should be replaced withActionableNotification
.- The
notificationType
prop is no longer needed and can be removed. - The default
role
is nowstatus
.log
andalert
can also be used. - The
closeOnEscape
prop toggles the closing of notifications via theescape
key.
InlineNotification
updates:
- The
actions
prop has been removed. AnInlineNotification
containing an action or interactive children should be replaced withActionableNotification
configured with theinline
prop. children
can no longer contain interactive elements.- The
notificationType
prop is no longer needed and can be removed. - The default
role
is nowstatus
.log
andalert
can also be used. - The
closeOnEscape
prop toggles the closing of notifications via theescape
key.
ActionableNotification
config options:
- The
inline
prop enables a styling variation resulting in a similar visual design toInlineNotification
. - 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 theescape
key.
- The deprecated prop
isMobile
is no longer needed and has been removed - The
className
prop is now applied to the outermost element ofNumberInput
imaginaryTarget
is no longer available on theonChange
event- The signature for
onChange
isonChange(event, {value, direction})
- To fully control a NumberInput, use
value
to track internal state updates
- The signature for
- This component has been updated from a class component to a functional component
- The prop
light
has been deprecated, use theLayer
component instead
- This component has been updated from a class component to a functional component
- The deprecated prop
primaryFocus
is no longer needed and has been removed. PreferselectorPrimaryFocus
on<OverflowMenu>
instead
- This component has been updated from a class component to a functional component
- The
className
prop is now applied to the outermost element ofNumberInput
- The deprecated prop
iconDescription
is no longer needed and has been removed - The
className
prop is now applied to the outermost element ofNumberInput
- This component has been updated from a class component to a functional component
- The deprecated prop
placeHolderText
has been removed. Please useplaceholder
instead - The deprecated prop
small
has been removed. Please usesize="sm"
instead - The
size
prop values have been updated such that:- If using
size="lg"
in v10, usesize="md"
- If using
size="xl"
in v10, usesize="lg"
- If using
- The deprecated prop
iconDescription
is no longer needed and has been removed - The
size
prop has been updated to:PropTypes.oneOf(['sm', 'md', 'lg'])
. Thexl
size is no longer supported - The
className
prop is now applied to the outermost element ofSelect
- This component has been updated from a class component to a functional component
- The deprecated prop
stepMuliplier
has been removed in favor ofstepMultiplier
- The
className
prop is now applied to the outermost element ofSlider
- The
ariaLabelInput
prop no longer has a default value and is now required
- The
defaultChecked
prop is no longer needed and has been deprecated - The
onChange
prop has been deprecated - The
value
prop has been deprecated
- The deprecated prop
shouldShowBorder
has been removed - The
size
prop has been updated to:PropTypes.oneOf(['xs', 'sm', 'md', 'lg', 'xl'])
. Previous values such ascompact
,short
,normal
,tall
, etc are no longer supported.
- The deprecated prop
persistant
has been removed. Please usepersistent
instead. - The deprecated prop
placeholderText
has been removed. Please useplaceholder
instead.
- The
className
prop is now applied to the outermost element ofTextInput
- The
size
prop has been updated to:PropTypes.oneOf(['sm', 'md', 'lg'])
. Thexl
size is no longer supported TextInput.ControlledPasswordInput
is no longer available, useControlledPasswordInput
directlyTextInput.PasswordInput
is no longer available, usePasswordInput
directly
- This component has been updated from a class component to a functional component
- The
light
prop for Tile has been deprecated. For layering, please use theLayer
component
- This component has been updated from a class component to a functional component
- The deprecated prop
handleClick
has been removed. UseonClick
instead - The deprecated prop
handleKeyDown
has been removed. useonKeyDown
instead
- The deprecated prop
handleClick
has been removed. UseonClick
instead - The deprecated prop
handleKeyDown
has been removed. UseonKeyDown
instead - The deprecated prop
iconDescription
is no longer needed and has been removed - The
light
prop for Tile has been deprecated. For layering, please use theLayer
component
- This component has been updated from a class component to a functional component
- The deprecated prop
handleClick
has been removed. UseonClick
instead - The
light
prop for Tile has been deprecated. For layering, please use theLayer
component
- This component has been updated from a class component to a functional component
- The
light
prop for Tile has been deprecated. For layering, please use theLayer
component
- The deprecated
iconDescription
prop is no longer needed and has been removed - The deprecated
hideLabel
prop has been removed
The toggle component has been updated to improve its accessibility, rtl compatibility and flexibility to layout.
- The underlying element has been changed from a checkbox
(
<input type="checkbox">
) to a switch button (<button role="switch">
).props.onChange
has been removed since it's not available on<button>
elements.props.onClick
has been added to substitute the previousonChange
event.
props['aria-label']
is no longer required.props.labelText
will always be available to screen readers without the use ofaria-label
.- If
props['aria-label']
is still passed, it will be emitted on the<button>
element.
props.hideLabel
has been added. This hideslabelA
andlabelB
while movinglabelText
to the side for height-restricted layouts.props.labelA
andprops.labelB
have been made optional and default to "Off" and "On" respectively.
Tabs have been updated to be more composable so that you have the flexibity and control to make them look and act how you want.
In v10, you may have code that looks like the following:
<Tabs>
<Tab label="Tab label 1">
<p>Content for first tab goes here.</p>
</Tab>
<Tab label="Tab label 2">
<p>Content for second tab goes here.</p>
</Tab>
<Tab label="Tab label 3" disabled>
<p>Content for third tab goes here.</p>
</Tab>
<Tab
label="Tab label 4 shows truncation"
title="Tab label 4 shows truncation">
<p>Content for fourth tab goes here.</p>
</Tab>
</Tabs>
Those same Tabs, migrated to v11:
<Tabs>
<TabList>
<Tab>Tab Label 1</Tab>
<Tab>Tab Label 2</Tab>
<Tab disabled>Tab Label 3</Tab>
<Tab title="Tab Label 4 shows truncation">Tab Label 4 shows truncation</Tab>
</TabList>
<TabPanels>
<TabPanel>Content for first tab goes here.</TabPanel>
<TabPanel>Content for second tab goes here.</TabPanel>
<TabPanel>Content for third tab goes here.</TabPanel>
<TabPanel>Content for fourth tab goes here.</TabPanel>
</TabPanels>
</Tabs>
All the same functionality for Tabs is available in v11 and more! However, some props have been deprecated becuase they have either been renamed or are no longer needed. Below are the minor tweaks in naming or implementation.
- the
type
prop is deprecated. Both "container" and "default" tabs still exist but now can be called by adding the propcontained
to theTabList
. - Default tabs are now referred to as line tabs in our documentation here and in our storybook.
hidden
prop is no longer needed with the new composable Tabs. You have control over tab content and when it is hidden through theTabPanel
andTabPanels
components.selected
prop is now namedselectedIndex
.tabContentClassName
is no longer needed.TabPanel
(equivalent to tab content) takes in a className prop on its outermost node.- For
Tab
,label
is no longer needed.children
ofTab
are now the label. - Due to its composability,
renderAnchor
,renderButton
,renderContent
are no longer needed onTab
. You now have full control over what is rendered inside ofTab
andTabPanel
. - Because
renderButton
is no longer needed, the associatedtabIndex
prop has also been deprecated. selected
onTab
is deprecated in favor orselectedIndex
, now placed onTabs
instead.
For more details about the changes to Tabs, see our storybook documentation here.
Starting in v11, the Tooltip
, TooltipDefinition
, and TooltipIcon
components have been updated in order to be made accessible. In particular,
- The API of Tooltip has been updated. In particular, this component should only include interactive content
- TooltipDefinition has been renamed to DefinitionTooltip
- TooltipIcon has been removed, use
IconButton
instead
For interactive content use-cases inside of Tooltips, we have introduced a new
component: Toggletip
.
This component has been updated so that it will add a tooltip to any interactive child element that is passed to this component. For example:
import { Tooltip } from '@carbon/react';
function ExampleComponent() {
return (
<Tooltip label="Close">
<button type="button">X</button>
</Tooltip>
);
}
This component accepts two ways to specify the content of the tooltip: label
and description
. These components accept either a string or a component and
they must not contain interactive content. If you have a tooltip which contains
interactive content, use a Toggletip instead.
As a result of these changes, certain props are no longer applicable in v11, including:
- focusTrap: this component no longer requires this behavior
- iconName
- menuOffset
- renderIcon: this is now the content of Tooltip
- selectorPrimaryFocus: this component no longer requires this behavior
- showIcon: this is now controlled by the children of Tooltip
- tooltipBodyId: this component no longer requires this behavior
- tooltipId: this component no longer requires this behavior
- triggerClassName: this is now controlled by the children of Tooltip
- triggerText
- iconDescription: this is now replaced by
label
ordescription
Certain props are not available in v11 but will be available soon. For example,
autoOrientation
will be available under align="auto"
.
In addition, the align
and direction
props have been updated to a single
prop: align
.
For full documentation on this component, check out our Storybook
This component has been renamed to DefinitionTooltip
. There are two notable
changes to this component:
- The
tooltipText
prop has been renamed todefinition
- The
align
anddirection
props have been merged into thealign
prop
For full documentation on this component, check out our Storybook
This component was problematic in v10 because the tooltip was being added to an
element that was not interactive. In order to ship an accessible version of this
component, we now have an IconButton
component that can be used as a
replacement for TooltipIcon
. If you have a situation where your content is not
related to a button or action, please reach out! We'll help you find a good way
to migrate your work in v10.
As a result, in places where you are using TooltipIcon
you can use
IconButton
.
Before
import { TooltipIcon } from 'carbon-components-react';
function ExampleComponent() {
return (
<TooltipIcon
tooltipText="Example tooltip"
onClick={() => {
// ...
}}
renderIcon={Filter}
/>
);
}
After
import { IconButton } from '@carbon/react';
function ExampleComponent() {
return (
<IconButton
label="Example tooltip"
onClick={() => {
// ...
}}>
<Filter />
</IconButton>
);
}
With this update, certain props are no longer needed or have been renamed. These include:
align
anddirection
have been merged intoalign
renderIcon
this is now whatever you render as the child ofIconButton
tooltipText
this has been renamed tolabel
For full documentation on this component, check out our Storybook
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:
Package | Framework | Link |
---|---|---|
@carbon/icons-react |
React | Link |
@carbon/icons-angular |
Angular | Link |
@carbon/icons-vue |
Vue | Link |
carbon-icons-svelte |
Svelte | Link |
@carbon/icons |
Vanilla JavaScript | Link |
Changes
- The
scss
directory which provided styles is no longer provided through this package - The following assets that were deprecated in v10 have been removed:
- app-switcher
- arrows
- back-to-top
- checkbox--undeterminate
- checkbox--undeterminate--filled
- cloud--lightning
- cloud--rain
- cloud--snow
- delete
- edit-filter
- sunny
- research--bloch-sphere
- research--hinton-plot
- research--matrix
- misuse--alt
- logo--google
- mammogram--stacked
- logo--delicious
- logo--stumbleupon
- letter--Aa--large
- glyph--caution-inverted
- glyph--caution
- glyph--circle-fill
- glyph--circle-stroke
- glyph--critical
- glyph--incomplete
- glyph--square-fill
- glyph--undefined
The @carbon/icons-react
package has been updated to minimize the number of
exports from the package to help reduce build and compile times. It also has
been updated to remove icons that were deprecated in v10.
If you are using @carbon/react, you can now import icons directly from @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.
Before
import { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';
function MyComponent() {
return (
<>
<Add32 />
<Add24 />
<Add20 />
<Add16 />
</>
);
}
After
import { Add } from '@carbon/icons-react';
function MyComponent() {
return (
<>
<Add size={32} />
<Add size={24} />
<Add size={20} />
<Add />
</>
);
}
The following deprecated icons have been removed. Use the table below to find their replacement, if available, in v11.
Asset | v10 | v11 |
---|---|---|
app-switcher | AppSwitcher | Switcher |
arrows | Arrows | ArrowsVertical |
back-to-top | BackToTop | UpToTop |
checkbox--undeterminate | CheckboxUndeterminate | CheckboxIndeterminate |
checkbox--undeterminate--filled | CheckboxUndeterminateFilled | CheckboxIndeterminateFilled |
cloud--lightning | CloudLightning | Removed |
cloud--rain | CloudRain | Removed |
cloud--snow | CloudSnow | Removed |
delete | Delete | TrashCan |
edit-filter | EditFilter | FilterEdit |
sunny | Sunny | Removed |
research--bloch-sphere | ResearchBlockSphere | BlochSphere |
research--hinton-plot | ResearchHintonPlot | HintonPlot |
research--matrix | ResearchMatrix | Matrix |
misuse--alt | MisuseAlt | MisuseOutline |
logo--google | LogoGoogle | Removed |
mammogram--stacked | MammogramStacked | Removed |
logo--delicious | LogoDelicious | Removed |
logo--stumbleupon | LogoStumbleUpon | Removed |
letter--Aa--large | LetterAaLarge | TextFont |
glyph--caution-inverted | GlyphCautionInverted | CautionInverted |
glyph--caution | GlyphCaution | Caution |
glyph--circle-fill | GlyphCircleFill | CircleFill |
glyph--circle-stroke | GlyphCircleStroke | CircleStroke |
glyph--critical | GlyphCritical | Critical |
glyph--incomplete | GlyphIncomplete | Incomplete |
glyph--square-fill | GlyphSquareFill | SquareFill |
glyph--undefined | GlyphUndefined | Undefined |
Most use-cases of the icons from the @carbon/icons-react
package will be
covered by an automated codemod. To run this codemod, follow the instructions in
@carbon/upgrade
.
Update imports and size usage for @carbon/icons-react
npx @carbon/upgrade migrate icons-react-size-prop
However, in certain situations, we will be unable to infer what the correct update should be for a certain usage of the icon component. We have written the codemod to work for most situations, but you will see console warnings for files that will require you to manually review them to make sure the transforms were applied correctly.
The most common manual update that teams will need to make is if a prop
where
the icon is passed to places a ref
on the icon. For example,
function MyComponent({ renderIcon: Icon }) {
const ref = useRef(null);
return <Icon ref={ref} />;
}
// Before
<MyComponent renderIcon={Search16} />
// After the codemod
<MyComponent renderIcon={props => <Search size={16} {...props} />} />
In this situation, you will need to update your code to use React.forwardRef
:
<MyComponent
renderIcon={React.forwardRef((props, ref) => (
<Search ref={ref} size={16} {...props} />
))}
/>;
// Or, alternatively:
const Search16 = React.forwardRef((props, ref) => {
return <Search ref={ref} size={16} {...props} />;
});
<MyComponent renderIcon={Search16} />;
In addition to the automated codemods above, there are several patterns in your codebase that you will need to update manually:
- If you use the name
ForwardRef(IconName16)
in a test you will need to manually change this. Prefer to use the component directly if using enzyme - If you use snapshot tests, the structure will change and include a
size
prop. Make sure that thesize
prop value matches what your icon name used to be. For example,<Add16 />
should become<Add size={16} />
If you use eslint
you may run into the error message above. This comes from
the react/display-rule
rule. It comes as a result of the transform changing
the following code:
// Input
const iconTypes = {
add: Add32,
};
// Output
const iconTypes = {
add: (props) => <Add size={32} {...props} />,
};
The transform will create an inline arrow function expression and as a result it
does not have a displayName
like if you created this function using a variable
or function declaration.
To address this issue, you can manually create the component:
const Add32 = (props) => <Add size={32} {...props} />;
const iconTypes = {
add: Add32,
};
Breaking changes
- This package now requires Dart Sass and uses Sass Modules
- The
scss
folder is no longer needed, you can import@carbon/colors
directly in Sass - Variables and mixins with the
ibm--
prefix have been removed - Variables and mixins with the
carbon--
prefix have been removed
Imports
v10 | v11 |
---|---|
@import '@carbon/colors/scss/index'; |
@use '@carbon/colors'; |
@use '@carbon/react/scss/colors'; |
|
@use '@carbon/styles/scss/colors'; |
|
@import '@carbon/colors/scss/colors'; |
@use '@carbon/colors'; |
@use '@carbon/react/scss/colors'; |
|
@use '@carbon/styles/scss/colors'; |
Sass API
v10 | v11 |
---|---|
$<swatch>-<grade> , for example $blue-50 |
No changes |
$<swatch>-<grade>-hover , for example $blue-50-hover |
No changes |
$ibm-color__<swatch>-<grade> |
Removed, use $<swatch>-<grade> directly |
$ibm-color-map |
Removed, replaced by $colors |
@mixin ibm--colors |
Removed |
$carbon--<swatch>-<grade> |
Removed, use $<swatch>-<grade> directly |
$carbon--colors |
Removed, replaced by $colors |
@mixin carbon--colors |
Removed |
For full Sass API documentation, visit the Sass Documentation for this package.
JavaScript API
v10 | v11 |
---|---|
yellow |
This variable no longer refers to a color and instead refers to the swatch. Use yellow30 instead |
orange |
This variable no longer refers to a color and instead refers to the swatch. Use orange40 instead |
Breaking changes
- This package now requires Dart Sass and uses Sass Modules
- The
scss
folder is no longer needed, you can import@carbon/elements
directly in Sass
Imports
v10 | v11 |
---|---|
@import '@carbon/elements/scss/index'; |
@use '@carbon/elements'; |
@import '@carbon/elements/scss/elements'; |
@use '@carbon/elements'; |
Sass API
This package re-exports from other packages that make up the IBM Design Language. For more information about exports, refer to the individual package documentation to see what has changed. These packages include:
For full Sass API documentation, visit the Sass Documentation for this package.
v10 | v11 |
---|---|
@import '@carbon/grid/scss/grid'; |
@use '@carbon/grid'; |
(alias) | @use '@carbon/styles/scss/grid'; |
(alias) | @use '@carbon/react/scss/grid'; |
Changes
- This package now requires Dart Sass and uses Sass Modules
- The default number of columns has been changed to 16
- The grid package has been updated to include a CSS Grid implementation of the
grid
- This include supports for subgrid in CSS Grid
- Variables, mixins, and functions with the
carbon--
prefix have been renamed
Filename | v10 | v11 |
---|---|---|
scss/grid.scss |
Moved to index.scss |
|
scss/index.scss |
Moved to index.scss |
|
scss/_breakpoint |
New, this has moved from @carbon/layout |
|
$grid-gutter--condensed |
$grid-gutter |
|
scss/_css-grid.scss |
New | |
scss/_flex-grid.scss |
New | |
scss/_mixins.scss |
Moved to scss/_flex-grid.scss |
|
$carbon--aspect-ratios |
Moved to @carbon/styles/scss/components/aspect-ratio |
|
carbon--grid |
Renamed to @mixin flex-grid |
|
scss/_prefix.scss |
Moved to scss/_config.scss under $prefix |
|
scss/12.scss |
This file has been removed, configure $flex-grid-columns to 12 to emulate this entrypoint |
For full documentation, visit the Sass Documentation for the package.
Breaking changes
- This package now requires Dart Sass and uses Sass Modules
- Variables, mixins, and functions using the
carbon--
prefix has been renamed - The layout scale has been replaced with steps in the spacing scale
- Breaking and grid functions, mixins, and variables have been moved to the
@carbon/grid
package
Imports
v10 | v11 |
---|---|
@import '@carbon/layout/scss/layout'; |
@use '@carbon/layout'; |
@use '@carbon/styles/scss/spacing'; |
|
@use '@carbon/react/scss/spacing'; |
|
@import '@carbon/layout/scss/index'; |
@use '@carbon/layout'; |
@use '@carbon/styles/scss/spacing'; |
|
@use '@carbon/react/scss/spacing'; |
Changes
Filename | v10 | v11 |
---|---|---|
scss/_breakpoint.scss |
Moved to @carbon/grid , use directly from package or from @carbon/styles/scss/breakpoint or @carbon/react/scss/breakpoint |
|
scss/_convert.scss |
$carbon--base-font-size |
Renamed to $base-font-size |
@function carbon--rem |
Renamed to @function rem |
|
@function carbon--em |
Renamed to @function em |
|
scss/_key-height.scss |
@function carbon--get-column-width |
Removed |
$carbon--key-height-scales |
Removed | |
@function carbon--key-height |
Removed | |
scss/_mini-unit.scss |
$carbon--mini-unit-size |
Removed |
@function carbon--mini-units |
Removed | |
scss/_spacing.scss |
$carbon--spacing-01 |
Removed, use $spacing-01 instead |
$carbon--spacing-02 |
Removed, use $spacing-02 instead |
|
$carbon--spacing-03 |
Removed, use $spacing-03 instead |
|
$carbon--spacing-04 |
Removed, use $spacing-04 instead |
|
$carbon--spacing-05 |
Removed, use $spacing-05 instead |
|
$carbon--spacing-06 |
Removed, use $spacing-06 instead |
|
$carbon--spacing-07 |
Removed, use $spacing-07 instead |
|
$carbon--spacing-08 |
Removed, use $spacing-08 instead |
|
$carbon--spacing-09 |
Removed, use $spacing-09 instead |
|
$carbon--spacing-10 |
Removed, use $spacing-10 instead |
|
$carbon--spacing-11 |
Removed, use $spacing-11 instead |
|
$carbon--spacing-12 |
Removed, use $spacing-12 instead |
|
$carbon--spacing-13 |
Removed, use $spacing-13 instead |
|
$carbon--spacing |
Removed, use $spacing instead |
|
$spacing-01 |
No changes | |
$spacing-02 |
No changes | |
$spacing-03 |
No changes | |
$spacing-04 |
No changes | |
$spacing-05 |
No changes | |
$spacing-06 |
No changes | |
$spacing-07 |
No changes | |
$spacing-08 |
No changes | |
$spacing-09 |
No changes | |
$spacing-10 |
No changes | |
$spacing-11 |
No changes | |
$spacing-12 |
No changes | |
$spacing-13 |
No changes | |
$carbon--layout-01 |
Removed, use $spacing-05 instead |
|
$carbon--layout-02 |
Removed, use $spacing-06 instead |
|
$carbon--layout-03 |
Removed, use $spacing-07 instead |
|
$carbon--layout-04 |
Removed, use $spacing-09 instead |
|
$carbon--layout-05 |
Removed, use $spacing-10 instead |
|
$carbon--layout-06 |
Removed, use $spacing-12 instead |
|
$carbon--layout-07 |
Removed, use $spacing-13 instead |
|
$carbon--layout |
Removed | |
$layout-01 |
Removed, use $spacing-05 instead |
|
$layout-02 |
Removed, use $spacing-06 instead |
|
$layout-03 |
Removed, use $spacing-07 instead |
|
$layout-04 |
Removed, use $spacing-09 instead |
|
$layout-05 |
Removed, use $spacing-10 instead |
|
$layout-06 |
Removed, use $spacing-12 instead |
|
$layout-07 |
Removed, use $spacing-13 instead |
|
$carbon--fluid-spacing-01 |
Removed, use $fluid-spacing-01 instead |
|
$carbon--fluid-spacing-02 |
Removed, use $fluid-spacing-02 instead |
|
$carbon--fluid-spacing-03 |
Removed, use $fluid-spacing-03 instead |
|
$carbon--fluid-spacing-04 |
Removed, use $fluid-spacing-04 instead |
|
$carbon--fluid-spacing |
Removed, use $fluid-spacing instead |
|
$fluid-spacing-01 |
No changes | |
$fluid-spacing-02 |
No changes | |
$fluid-spacing-03 |
No changes | |
$fluid-spacing-04 |
No changes | |
$fluid-spacing |
No changes |
For full documentation, visit the Sass Documentation for the package.
JavaScript API
- The layout exports have been removed, use the spacing exports instead
v10 | v11 |
---|---|
layout01 |
spacing05 |
layout02 |
spacing06 |
layout03 |
spacing07 |
layout04 |
spacing09 |
layout05 |
spacing10 |
layout06 |
spacing12 |
layout07 |
spacing13 |
layout |
Removed |
Breaking changes
- This package now requires Dart Sass and uses Sass Modules
- The
scss
folder is no longer needed, you can import@carbon/motion
directly in Sass - Variables, mixins, and functions using the
carbon--
prefix has been renamed - Duration variables now have a
duration-
prefix
Imports
v10 | v11 |
---|---|
@import '@carbon/motion/scss/motion'; |
@use '@carbon/motion'; |
@use '@carbon/styles/scss/motion'; |
|
@use '@carbon/react/scss/motion'; |
|
@import '@carbon/motion/scss/index'; |
@use '@carbon/motion'; |
@use '@carbon/styles/scss/motion'; |
|
@use '@carbon/react/scss/motion'; |
Sass API
v10 | v11 |
---|---|
$fast-01 |
Renamed to $duration-fast-01 |
$fast-02 |
Renamed to $duration-fast-02 |
$moderate-01 |
Renamed to $duration-moderate-01 |
$moderate-02 |
Renamed to $duration-moderate-02 |
$slow-01 |
Renamed to $duration-slow-01 |
$slow-02 |
Renamed to $duration-slow-02 |
$carbon--easings |
Renamed to $easings |
@function carbon--motion |
Renamed to @function motion |
@mixin carbon--motion |
Renamed to @mixin motion |
For full documentation, visit the Sass Documentation for the package.
Breaking changes
- This package now requires Dart Sass and uses Sass Modules
- Variables, mixins, and functions with the
carbon--
prefix have been renamed - Design Tokens have been changed, however you can use the compatibility docs to use v10 tokens along with v11 tokens
- The
theme
mixin now emits CSS Custom Properties by default for the given theme,$emit-custom-properties
and$emit-difference
are no longer needed
Imports
v10 | v11 |
---|---|
@import '@carbon/themes/scss/themes'; |
@use '@carbon/themes'; |
@use '@carbon/styles'; |
|
@use '@carbon/react/scss/themes'; |
|
@import '@carbon/themes/scss/index'; |
@use '@carbon/themes'; |
@use '@carbon/styles/scss/theme'; |
|
@use '@carbon/react/scss/theme'; |
|
@import '@carbon/themes/scss/theme-maps'; |
@use '@carbon/themes/scss/themes'; |
@use '@carbon/styles/scss/themes'; |
|
@use '@carbon/react/scss/themes'; |
Sass API
Filename | v10 | v11 |
---|---|---|
scss/_mixins.scss |
Moved to scss/theme |
|
@mixin carbon--theme |
Renamed to @mixin theme |
|
scss/_theme-maps.scss |
Moved to scss/themes |
|
$carbon--theme--white |
Renamed to $white |
|
$carbon--theme--g10 |
Renamed to $g10 |
|
$carbon--theme--g90 |
Renamed to$g90 |
|
$carbon--theme--g100 |
Renamed $g100 |
|
scss/_tokens.scss |
Tokens have been changed, use the compatibility theme or switch to the new tokens | |
scss/themes.scss |
Moved to @carbon/themes |
|
scss/index.scss |
Moved to @carbon/themes |
For full Sass API documentation, visit the Sass Documentation for this package.
JavaScript API
v10 | v11 |
---|---|
Token exports | The names and values of tokens have been updated in v11. Access v10 values through the v10 export |
white |
Updated with new tokens and values. For the v10 white theme, use the v10 export |
g10 |
Updated with new tokens and values. For the v10 g10 theme, use the v10 export |
g80 |
Removed |
g90 |
Updated with new tokens and values. For the v10 g90 theme, use the v10 export |
g100 |
Updated with new tokens and values. For the v10 g100 theme, use the v10 export |
v9 |
Removed |
themes |
Updated with new tokens and values. For the v10 themes, use the v10 export |
The v10
export has been added to access old token and theme values. To access
the v10 version of a theme, you can use this export directly:
import { v10 } from '@carbon/themes';
const { white, g10, g90, g100 } = v10;
Status key:
- No change: Token name has no change between versions.
- Updated: From v10 to V11 the number suffix has been replaced with an adjective that reflects it's usage. This is just a name change, the role remains the same between v10 and v11.
- Split: V10 token has been split into multiple new v11 tokens for more specific usage.
- New: A net new color token to the system in v11. It has no v10 counterpart.
- Deprecated: v10 token was removed in v11.
V10 token name | V11 token name | V11 Contextual token | Status |
---|---|---|---|
active-danger | button-danger-active | — | Updated |
active-light-ui | layer-active-02 | layer-active | Updated |
active-primary | button-primary-active | — | Updated |
active-secondary | button-secondary-active | — | Updated |
active-tertiary | button-tertiary-active | — | Updated |
active-ui | layer-active-01 | layer-active | Split |
active-ui | background-active | — | Split |
active-ui | layer-accent-active-01 | layer-accent-active | Split |
active-ui | border-subtle-selected-01 | border-subtle-selected | Split |
button-separator | button-separator | — | No change |
danger | button-danger-primary | — | Deprecated |
danger-01 | button-danger-primary | — | Updated |
danger-02 | button-danger-secondary | — | Updated |
decorative-01 | border-subtle-02 | border-subtle | Updated |
disabled-01 | — | — | Deprecated |
disabled-02 | text-disabled | — | Split |
disabled-02 | icon-disabled | — | Split |
disabled-02 | button-disabled | — | Split |
disabled-02 | border-disabled | border-disabled | Split |
disabled-03 | icon-on-color-disabled | — | Split |
disabled-03 | layer-selected-disabled | — | Split |
disabled-03 | text-on-color-disabled | — | Split |
field-01 | field-01 | field | No change |
field-02 | field-02 | field | No change |
focus | focus | — | No change |
highlight | highlight | — | No change |
hover-danger | button-danger-hover | — | Updated |
hover-light-ui | layer-hover-02 | — | Updated |
hover-primary | button-primary-hover | — | Updated |
hover-primary-text | link-primary-hover | — | Updated |
hover-secondary | button-secondary-hover | — | Updated |
hover-selected-ui | background-selected-hover | — | Split |
hover-selected-ui | layer-accent-hover-01 | layer-accent-hover | Split |
hover-selected-ui | layer-selected-hover-01 | layer-selected-hover | Split |
hover-tertiary | button-tertiary-hover | — | Updated |
hover-ui | background-hover | — | Updated |
hover-ui | layer-hover-01 | layer-hover | Split |
hover-ui | field-hover-01 | field-hover | Split |
hover-ui | field-hover-02 | field-hover | Split |
icon-01 | icon-primary | — | Updated |
icon-02 | icon-secondary | — | Updated |
icon-03 | icon-on-color | — | Updated |
interactive-01 | button-primary | — | Updated |
interactive-01 | background-brand | — | Updated |
interactive-02 | button-secondary | — | Updated |
interactive-03 | button-tertiary | — | Updated |
interactive-04 | border-interactive | — | Split |
interactive-04 | interactive | — | Split |
inverse-01 | icon-inverse | — | Split |
inverse-01 | focus-inset | — | Split |
inverse-01 | text-inverse | — | Split |
inverse-02 | background-inverse | — | Updated |
inverse-focus-ui | focus-inverse | — | Updated |
inverse-hover-ui | background-inverse-hover | — | Updated |
inverse-link | link-inverse | — | Updated |
inverse-support-01 | support-error-inverse | — | Updated |
inverse-support-02 | support-success-inverse | — | Updated |
inverse-support-03 | support-warning-inverse | — | Updated |
inverse-support-04 | support-info-inverse | — | Updated |
link-01 | link-primary | — | Updated |
link-02 | link-secondary | — | Updated |
overlay-01 | overlay | — | Updated |
selected-light-ui | layer-selected-02 | — | Updated |
selected-ui | layer-selected-01 | layer-selected | Split |
selected-ui | background-selected | — | Split |
skeleton-01 | skeleton-background | — | Updated |
skeleton-02 | skeleton-element | — | Updated |
support-01 | support-error | — | Updated |
support-02 | support-success | — | Updated |
support-03 | support-warning | — | Updated |
support-04 | support-info | — | Updated |
text-01 | text-primary | — | Updated |
text-02 | text-secondary | — | Updated |
text-03 | text-placeholder | — | Updated |
text-04 | text-on-color | — | Updated |
text-05 | text-helper | — | Updated |
text-error | text-error | — | Updated |
hover-row | layer-hover-01 | layer-hover | Deprecated |
ui-01 | layer-01 | layer | Updated |
ui-02 | layer-02 | layer | Updated |
ui-03 | layer-accent-01 | layer-accent | Split |
ui-03 | border-subtle-01 | border-subtle | Split |
ui-04 | toggle-off | — | Split |
ui-04 | border-strong-01 | border-strong | Split |
ui-05 | border-inverse | — | Updated |
ui-05 | layer-selected-inverse | — | Updated |
ui-background | background | — | Updated |
visited-link | link-visited | — | Updated |
brand-01 | — | — | Deprecated |
brand-02 | — | — | Deprecated |
brand-03 | — | — | Deprecated |
— | border-strong-02 | border-strong | New |
— | border-strong-03 | border-strong | New |
— | border-subtle-00 | border-subtle | New |
— | border-subtle-03 | border-subtle | New |
— | border-subtle-selected-02 | border-subtle-selected | New |
— | border-subtle-selected-03 | border-subtle-selected | New |
— | field-03 | field | New |
— | field-hover-03 | field-hover | New |
— | layer-03 | layer | New |
— | layer-active-03 | layer-active | New |
— | layer-hover-03 | layer-hover | New |
— | layer-selected-03 | layer-selected | New |
— | layer-selected-hover-02 | layer-selected-hover | New |
— | layer-selected-hover-03 | layer-selected-hover | New |
— | layer-accent-02 | layer-accent | New |
— | layer-accent-03 | layer-accent | New |
— | layer-accent-active-02 | layer-accent-active | New |
— | layer-accent-active-03 | layer-accent-active | New |
— | layer-accent-hover-02 | layer-accent-hover | New |
— | layer-accent-hover-03 | layer-accent-hover | New |
To make it easier to move between v10 and v11 of Carbon, we've introduced a compatibility theme that includes the tokens from v10 and v11 so that you can incrementally update your project.
You can use a "compatibility theme" by setting the $fallback
to a value from
scss/compat/themes
. For example:
@use '@carbon/react/scss/compat/themes' as compat;
@use '@carbon/react/scss/themes';
@use '@carbon/react/scss/theme' with (
$fallback: compat.$g100,
$theme: themes.$g100
);
@use '@carbon/react';
:root {
@include theme.theme();
}
In this code snippet, we set the current theme to $g100
and include the
compatibility theme for $g100
as the `$fallback.
Breaking changes
- This package now requires Dart Sass and uses Sass Modules
- The
scss
folder is no longer needed, you can import@carbon/type
directly in Sass - Variables, mixins, and functions with the
carbon--
prefix have been renamed
Imports
All imports in v11 have been replaced by @carbon/type
. For example, if you
were importing @carbon/type/scss/styles
in v10 you would now only import
@carbon/type
and use exports from that module directly.
v10 | v11 |
---|---|
@import '@carbon/type/scss/*'; |
@use '@carbon/type'; |
@use '@carbon/styles/scss/type'; |
|
@use '@carbon/react/scss/type'; |
Sass API
Filename | v10 | v11 |
---|---|---|
scss/index.scss |
Removed, use @carbon/type directly |
|
scss/type.scss |
Removed, use @carbon/type directly |
|
scss/_classes.scss |
@mixin carbon--type-classes |
Renamed to @mixin type-classes |
scss/font-face/_mono.scss |
@mixin carbon--font-face-mono |
Removed, use @carbon/styles/scss/fonts |
scss/font-face/_sans-condensed.scss |
@mixin carbon--font-face-condensed |
Removed, use @carbon/styles/scss/fonts |
scss/font-face/_sans.scss |
@mixin carbon--font-face-sans |
Removed, use @carbon/styles/scss/fonts |
scss/font-face/_serif.scss |
@mixin carbon--font-face-serif |
Removed, use @carbon/styles/scss/fonts |
scss/font-face/_settings.scss |
$carbon--font-display |
Removed |
scss/_font-family.scss |
$carbon--font-families |
Renamed to $font-families |
@function carbon--font-family |
Renamed to @function font-family |
|
@mixin carbon--font-family |
Renamed to @mixin font-family |
|
$carbon--font-weights |
Renamed to $font-weights |
|
@function carbon--font-weight |
Renamed to @function font-weight |
|
@mixin carbon--font-weight |
Renamed to @mixin font-weight |
|
scss/_prefix.scss |
No Changes | |
scss/_reset.scss |
@mixin carbon--default-type |
Renamed to @mixin default-type |
@mixin carbon--type-reset |
Renamed to @mixin type-reset |
|
scss/_scale.scss |
@function carbon--get-type-size |
Removed, use type-scale instead |
$carbon--type-scale |
Renamed to $type-scale |
|
@function carbon--type-scale |
Renamed to @function type-scale |
|
@mixin carbon--type-scale |
Renamed to @mixin type-scale |
|
@mixin carbon--font-size |
Renamed to @mixin font-size |
|
scss/_styles.scss |
@mixin carbon--type-style |
Renamed to @mixin type-style |
$caption-01 |
Removed | |
$caption-02 |
Removed |
Status key:
- No change: Token name has no change between versions.
- Updated: This is just a name change, the role remains the same between v10 and v11.
- New: A net new type token to the system in v11. It has no v10 counterpart.
- Deprecated: v10 token was removed in v11.
Category | V10 token name | V11 token name | Status |
---|---|---|---|
Utility styles | code-01 | code-01 | No change |
code-02 | code-02 | No change | |
label-01 | label-01 | No change | |
label-02 | label-02 | No change | |
helper-text-01 | helper-text-01 | No change | |
helper-text-02 | helper-text-02 | No change | |
legal-01 | New | ||
legal-02 | New | ||
caption-01 | Removed | ||
caption-02 | Removed | ||
Body styles | |||
body-short-01 | body-compact-01 | Updated | |
body-short-02 | body-compact-02 | Updated | |
body-long-01 | body-01 | Updated | |
body-long-02 | body-02 | Updated | |
Fixed heading styles | |||
productive-heading-01 | heading-compact-01 | Updated | |
productive-heading-02 | heading-compact-02 | Updated | |
expressive-heading-01 | heading-01 | Updated | |
expressive-heading-02 | heading-02 | Updated | |
productive-heading-03 | heading-03 | Updated | |
productive-heading-04 | heading-04 | Updated | |
productive-heading-05 | heading-05 | Updated | |
productive-heading-06 | heading-06 | Updated | |
productive-heading-07 | heading-07 | Updated | |
Fluid heading styles | |||
expressive-heading-03 | fluid-heading-03 | Updated | |
expressive-heading-04 | fluid-heading-04 | Updated | |
expressive-heading-05 | fluid-heading-05 | Updated | |
expressive-heading-06 | fluid-heading-06 | Updated | |
Fluid display styles | |||
expressive-paragraph-01 | fluid-paragraph-01 | Updated | |
quotation-01 | fluid-quotation-01 | Updated | |
quotation-02 | fluid-quotation-02 | Updated | |
display-01 | fluid-display-01 | Updated | |
display-02 | fluid-display-02 | Updated | |
display-03 | fluid-display-03 | Updated | |
display-04 | fluid-display-04 | Updated |