Skip to content

v4 to v5 upgrade guide

Jump to bottom
Akshat Patel edited this page Mar 6, 2025 · 4 revisions

General

Ivy is here! Angular project has been updated from v7 to v14. Going forward only angular versions v14 and above will be supported and with, we have enabled partial ivy compilation. - With this change, angular switches from node-sass to sass (dart)

  • IE is no longer supported, hence IE specific keys ('Down', 'Esc', 'Up', etc.) & conditions have been removed.
  • Peer dependencies now list @carbon/styles instead of carbon-components package.
    • To get started with dart sass, checkout the @carbon/styles documentations.
    • All class prefixes within components have been updated from bx-- to cds--, an abbreviation of Carbon Design System.
  • You can view the migration guide from carbon-components to @carbon/styles here.

@Carbon/icons-angular

We have officially deprecated the @carbon/icons-angular package in favor of @carbon/icons. You'll now see a deprecation notice when you run your install scripts.

@carbon/icons is the main icons package for Carbon Design System, hence you'll get updates as soon as they are made. Additionally, the unpacked size is significantly lower, 38MB compared to 148MB.

To get started with @carbon/icons check out the code sandbox demo.

There are comments added to files to guide you through the usage. The relevant files to look at are:

Common changes

Size prop (breaking change)

  • Carbon 11 aims to add consistency in sizing options for all relevant components. In v4, we offered sm, md, xl. This has been updated to sm, md, lg.
  • Form components no longer accepts xl value for size, instead use lg.

Old:

<ibm-date-picker size="xl"></ibm-date-picker>

New:

<cds-date-picker size="lg"></cds-date-picker>

Component/directive prefix update

  • All component and directive prefixes have been changed from ibm to cds. This change is made to better align with carbon-design-system github organization.
  • We still support ibm prefix, but we plan on deprecating it before v6. We recommend teams move to cds prefix for CCA.

Old:

<ibm-date-picker></ibm-date-picker>
<svg ibmIcon="fade" size="16"></svg>

New:

<cds-date-picker></cds-date-picker>
<svg cdsIcon="fade" size="16"></svg>

Theme prop

  • theme property is now deprecated for all relevant component. Instead, we recommend you start start using the new cdsLayer directive to apply light/dark theme.

Old:

<ibm-date-picker theme="light"></ibm-date-picker>
<ibm-select theme="light">...</ibm-select>

New:

<!-- The following code will apply `light` theme to all supported components in the div -->
<div cdsLayer>
	<cds-date-picker></cds-date-picker>
	<cds-select>...</cds-select>
</div>
  • Dark theme is the default value for the theme property. If you need to set the theme to dark, you can pass 0 or 2.
<!-- The following code will apply `dark` theme to all supported components in the div -->
<div cdsLayer="0">
	<cds-date-picker></cds-date-picker>
	<cds-select>...</cds-select>
</div>

Changelog

Components not listed have minimal changes and should not effect your migration.

  • Accordion

    • Added new input properties:
      • disable - prevents accordion item from being expanded.
      • size - sets the size of the accordion item.
    • Template has been updated to remove list items (ul, li) to provide better accessibility using role.

  • Button

    • Button directive has major changes. The directive no longer supports standalone icons, instead use the newly cds-icon-button component.

    • cdsButton (Directive)

      • size types have been updated to be consistent with other components. We longer supports field value, instead use md. A new size option has also been added 2xl. Hence, following size options can now be used: sm, md (default), lg, xl, 2xl.
      • type (Button type), no longer accepts toolbar-action as a value as it was not used in v4.
      • Button directive no longer supports assistive text (tooltips for icon), hence hasAssistiveText, assistiveTextPlacement, assistiveTextAlignment input properties have been removed, if you use these options switch to Icon button.

    • Icon button

      Old: New: 
      <button
	[iconOnly]="true"
	[hasAssistiveText]="true"
	assistiveTextPlacement="top"
	assistiveTextAlignment="left">
	<svg class="bx--btn__icon" ibmIcon="copy" size="16"></svg>
	<span class="bx--assistive-text">Icon description</span>
</button>
      		 
      <!-- `assistiveTextPlacement` & `assistiveTextAlignment` 
have been combined to a single input -->
<cds-icon-button
	align="top-left"
	description="Icon description">
	<svg class="cds--btn__icon" cdsIcon="copy" size="16"></svg>
</cds-icon-button>
      • You can use align property to set the alignment & placement of the assistive text.
      • With the changes to tooltip, standalone icon buttons have been separated into a new component. The component covers most of the use cases, but you may need to create a custom icon button. To do so, a BaseIconButton component has been created to help you get started.
      • You will be able to pass in attributes & global classes, see storybook & docs for examples.

  • Checkbox

    • CheckboxChange class has been removed.

    • change output binding has been removed, instead use the checkedChange.

    • checked now supports two-way binding.

      Old: New: 
      <ibm-checkbox (change)="change($event)">
	Checkbox
</ibm-checkbox>
      		 
      <cds-checkbox (checkedChange)="change($event)">
	Checkbox
</cds-checkbox>
      		 
      <ibm-checkbox (change)="change($event)">
	Checkbox
</ibm-checkbox>
      		 
      <!-- double bind -->
<cds-checkbox [(checked)]="checked">
	Checkbox
</cds-checkbox>

    • size and nested are no longer supported input properties, they were not used in v4 - remove them.

    • aria-label input is now renamed too ariaLabel to avoid assigning aria property to component tag.

    • aria-labelledby input is now renamed to ariaLabelledby to avoid assigning aria property to component tag.

      Old: New: 
      <ibm-checkbox
	aria-label="Label"
	ariaLabelledby="label-id-1">
	Checkbox
</ibm-checkbox>
      		 
      <cds-checkbox
	ariaLabel="Label"
	ariaLabelledby="label-id-1">
	Checkbox
</cds-checkbox>

  • Code snippet

    • Code snippet has been rewritten & now uses cds-icon-button component.
    • There are more Input properties to customize code snippet.
      • min/max number of expanded rows, min/max number of collapsed rows, etc. Visit the storybook/documentation to play around with these new properties!
    • Now uses the navigator (browser) API for copying.

  • Combobox

    • Now applies disabled styling to label/helper text.
    • All size classes are applied, including md (default).
      • Size option no longer accepts xl value, use lg instead.
    • Theme has been marked as deprecated, use cdsLayer instead.

  • Content Switcher

    • theme property wasn't used and has been removed, if you passed this property, remove it.

  • Context Menu

    • Context menu has been rewritten.
    • Template has been updated to remove list items (ul, li) to provide better accessibility using role.

  • Datepicker Input

    • Now applies disabled styling to label/helper text.
    • All size classes are applied, including md (default).
      • Size option no longer accepts xl value, use lg instead.
    • Theme has been marked as deprecated, use cdsLayer instead.

  • Date Picker

    • Custom styling has been removed. If you have used .dayContainer css class to target the component, use the component selector.

    • pattern input has been renamed to inputPattern for more clarity.

      Old: New: 
      <ibm-date-picker 
	pattern="pattern">
</ibm-date-picker>
      		 
      <ibm-date-picker 
	inputPattern="pattern">
</ibm-date-picker>

    • Size option no longer accepts xl value, use lg instead.

    • Theme has been marked as deprecated, use cdsLayer instead.

  • Dialog

    • closeAll function in dialog.service.ts has been removed, use the static DialogService.closeAll function instead.
    Old: New: 
     const dialogService = inject(DialogService);
 func() {
 	// Deprecated
 	dialogService.closeAll();
 }
    		 
     func() {
 	DialogService.closeAll();
 }

    • Module no longer exports Tooltip, TooltipDefinition, TooltipIcon,TooltipDirective or EllipsesTooltip. See tooltip changes below.

    • Dialog directive
      • open function now accepts an optional component class to open in dialog.
    • Dialog service
      • With changes to Angular 14, ComponentFactoryResolver is no longer injected. We now pass the desired component directly to the placeholder service to render.
    • Overflow menu custom pane
      • Component has been marked as deprecated and will be removed in future versions of Angular. Instead, use the newly created Toggletip or Popover components which provide more functionality.
      Old: New: 
      	<ng-template #templateRef>
		<div>
			TEMPLATE
		</div>
	</ng-template>
	<!-- Content rendered in placeholder -->
	<button
		[ibmOverflowMenu]="templateRef"
		[customPane]="true"
		placement="bottom">
		<svg ibmIcon="settings" size="16"></svg>
	</button>
	<ibm-placeholder></ibm-placeholder>
      		 
      <cds-toggletip align="bottom">
	<button cdsToggletipButton>
		<svg ibmIcon="settings" size="16"></svg>
	</button>
	<!-- Content is now inline -->
	<div cdsToggletipContent>
		<div>
			TEMPLATE
		</div>
	</div>
</cds-toggletip>

  • Dropdown

    • Now applies disabled styling to label/helper text.
    • All size classes are applied, including md (default).
      • Size option no longer accepts xl value, use lg instead.
    • value input has been removed, use itemValueKey instead.
    • Theme has been marked as deprecated, use cdsLayer instead.
  • File Uploader
    • invalidTitle is a new optional file item attribute, use it to add a summary of the invalid message.
    • The button size type is now consistent with button directive, normal is no longer an acceptable size option. Use sm, md, or lg.
    Old: New: 
     <ibm-file-uploader size="normal">
 	...
 </ibm-file-uploader>
    		 
     	<cds-file-uploader size="lg">
 		...
 	</cds-file-uploader>
    • You can now set the size of the file item (sm, md, lg (default)) of the file item.

  • Grid/Row/Columns

    • Grid

      • Now supports css grid, set useCssGrid to true to enable. Enabling css grid will automatically update columns to css grid classes. CSS Grid is the default grid enabled by carbon styles.
      • Import the grid variant in your styles.scss to get started. We strongly recommend taking a look at the storybook examples to see the new grid options.
      Old: New: 
      // Previously you had to import styles
@import '~carbon-components/css/carbon-components';
      		 
      // Specify the grid type you want to use, v4 uses `flex-grid`
// No need to set feature flag to true if you want to use css grid
@use '@carbon/styles' with (
	$use-flexbox-grid: true	
);
// or directly import if you want to use both types of grids
@use '@carbon/styles/scss/grid/flexbox';

    • Row

      • leftGutter, rightGutter, & condensed input have been removed as they are not supported in v11. If you are using these props, remove them.

    • Column

      • New css grid input properties, view Storybook to see the new changes.
  • i18n
    • We've removed strings that aren't used in any components.
  • Icon
    • You can now dynamically change the icon via cdsIcon input, just make sure it is registered!

  • Label

    • Now applies disabled styling to label/helper text.
    • Theme has been marked as deprecated, use cdsLayer instead. This change applies to both cdsText & cdsTextArea directives
    • labelState has been input property has now been removed in cds-label component, remove it.
    • Input (Directive)
      • All size classes are applied, including md (default).
      • Size option no longer accepts xl value, use lg instead.

  • Layer

    • A directive that applies layering style to the element it is applied to. This component is an alternative way to apply light & dark theme to components. You'll notice that going forward, theme input has been marked as deprecated for most components.
    • Setting level via ibmLayer input will automatically update child levels.
    • View storybook for more information.
  • Layout
    • Utility directive(s) to help with layout. cdsStack directive enables you to use the spacing scale to determine the gap between each stack item.

  • Modal

    • FYI - Since we now use partial-ivy compilation, we removed a remote scoping error from ModalService. A BaseModalService is now introduced, but no change is required on your end.
    • Modal now accepts md as a size option and is the default value now.
    • close event is now emitted on Escape keydown.
    • Modal Header
      • theme is now marked as deprecated
    • Modal Service
      • No longer have to inject ComponentFactoryResolver if you extend modal service due to Angular 14 changes.

  • Notification

    • Notification components have been updated to be more accessible out of the box. inline-notification (default) & toast have the role attribute set to status by default, with additional role options of log & alert.

    • For notifications requiring actions, use the new ActionableNotification component, which has the role attribute set to alertdialog.

    • info-square & warning-alt types have been added to all notification variants (inline, toast, actionable).

    • For all notifications, vertical margin have been removed. You can assign the container the new ibmStack layout directive to evenly space the notifications.

    • Due to role changes, toast & inline-notification, no longer support interactive elements (Links, additional buttons, etc.). It is still possible to pass in buttons if you use templates, however, it is highly recommended you switch to the new actionable-notification component.

      • Actionable-notification (New)
        • Supports interactive elements.
        • Set notificationObj.variant to inline or toast to enable respective styling variation.
        • Like toast & inline-notifcation, there are directives to help build custom actionable notifications (ActionableTitle, ActionableSubtitle, ActionableButton).
        • View demos at Carbon Angular storybook
      Old: New: 
      <ibm-notification 
	[notificationObj]="{
		type: 'success',
		title: 'Sample notification',
		message: 'Sample success message',
		actions: actions
	}">
</ibm-notification>
       actionSubject = new Subject<any>();
 actions = [
 	{
 		text: "Action",
 		click: this.actionSubject
 	}
 ]
      		 
      <cds-actionable-notification
	[notificationObj]="{
		variant: 'inline'
		type: 'success',
		title: 'Sample notification',
		message: 'Sample success message'
	}">
</cds-actionable-notification>
       actionSubject = new Subject<any>();
 actions = [
 	{
 		text: "Action",
 		click: this.actionSubject
 	}
 ]
      • Notification (Inline)
        • Interactive elements should NOT be used with this component, use actionable notification.
        • Now has two selectors, ibm-inline-notification & ibm-notification.
      • Toast

  • Number

    • All size classes are applied, including md (default).
      • Size option no longer accepts xl value, use lg instead.
    • Theme has been marked as deprecated, use cdsLayer instead.

  • Pagination Nav

    • Now wraps icon in IconButton component. Additional props (icon button) have been added to allow customization.

  • Popover

    • Popover directive & popover content component.
    • Content that layers over all other elements on page. The logic for all tooltips is based off the popover component. All tooltips extend popover.
    • For more information view carbondesignsystem or see storybook for usage in Angular.

  • Progress Indicator

    • Tooltips are no longer supported in V11, tooltip has been removed from Step interface.
      • Use secondary label.
    • Icons have been updated
    • Step interface has had some major changes to better manage progress state
      • text has been changed to label
      • optionalText is now secondaryLabel
      • state has been removed, instead we have created 2 additional properties complete & invalid that accept boolean values
      • Current state is now managed via current (index in array) input property. All steps preceding current are set to complete (Complete set to true) & following is set to incomplete (complete set to false).
      • Additionally, icons are displayed in the following weighted order current -> invalid -> complete -> incomplete
    Old: New: 
    <ibm-progress-indicator
	[steps]="steps">
</ibm-progress-indicator>
<ibm-placeholder></ibm-placeholder>
     steps = [
 	{
 		text: 'First',
 		optionalText: 'Optional text',
 		state: ['invalid', 'incomplete']
 	}
 ]
    		 
    <cds-progress-indicator
	[steps]="steps">
</cds-progress-indicator>
     steps = [
 	{
 		label: 'First',
 		secondaryLabel: 'Optional text',
 		complete: false,
 		invalid: true
 	}
 ]
  • Radio
    • Template has been updated to include fieldset, so you no longer have to set fieldset explicitly.
      • To go with this change, you can now pass in the legend as a string or a template.
    • invalid & warning states have been added.
    Old: New: 
    <fieldset class="bx--fieldset">
	<legend class="bx--label">LABEL</legend>
	<ibm-radio-group>
		<ibm-radio>Zero</ibm-radio>
		<ibm-radio>One</ibm-radio>
		<ibm-radio>Two</ibm-radio>
		<ibm-radio>Three</ibm-radio>
	</ibm-radio-group>
</fieldset>
    		 
    <!-- 
Wraps all radios in a fieldset now, 
can pass string or template in legend
-->
<ibm-radio-group legend="label">
	<ibm-radio>Zero</ibm-radio>
	<ibm-radio>One</ibm-radio>
	<ibm-radio>Two</ibm-radio>
	<ibm-radio>Three</ibm-radio>
</ibm-radio-group>
    		 
    <fieldset class="bx--fieldset">
	<legend class="bx--label">
		Label 
		<svg cdsIcon="fade"></svg>
	</legend>
	<ibm-radio-group>
		<ibm-radio>Zero</ibm-radio>
		<ibm-radio>One</ibm-radio>
		<ibm-radio>Two</ibm-radio>
		<ibm-radio>Three</ibm-radio>
	</ibm-radio-group>
</fieldset>
    		 
    <!-- Example with template -->
<ng-template #radioLegend>
	Label 
	<svg cdsIcon="fade"></svg>
</ng-template>
<ibm-radio-group legend="radioLegend">
	<ibm-radio>Zero</ibm-radio>
	<ibm-radio>One</ibm-radio>
	<ibm-radio>Two</ibm-radio>
	<ibm-radio>Three</ibm-radio>
</ibm-radio-group>

  • Search

    • Toolbar search is deprecated & removed in Carbon V11. (Wrapping ibm-search in div.cds--toolbar)
    • All size classes are applied, including md (default).
      • Size option no longer accepts xl value, use lg instead.
    • Theme has been marked as deprecated, use cdsLayer instead.

  • Select

    • Now applies disabled styling to label/helper text.
      • All size classes are applied, including md (default).
        • Size option no longer accepts xl value, use lg instead.
    • Custom component style have been removed.
    • Theme has been marked as deprecated, use cdsLayer instead.

  • Slider

    • Now applies disabled styling to label/helper text.

  • Structured List

    • Improved accessibility, styles are applied to row on focus event.
    • You can now dynamically set selected for a List Row
    • border & nowrap input did not apply any styles hence, removed. If you are using this prop, remove them.
    • You can now align content with margin using flushed property

  • Table

    • Drag & drop features from our legacy code base has been commented out until Carbon supports it out of the box.

    • Table no longer supports size sh, instead use xs.

    • Filter button has been removed from TableHeadCell as it was part of our legacy code base.

    • We've renamed change output to selectedChange to allow double binding for TableCheckbox component (ibmTableCheckbox/cdsTableCheckbox).

    Old: New: 
    <td
	ibmTableCheckbox
	(change)="onSelectionChange()">
</td>
    		 
    <td
	cdsTableCheckbox
	(selectedChange)="onSelectionChange()">
</td>
    • size input from cdsTableHeadCheckbox & cdsTableHead directive has been removed due to the removal in checkbox component. If you're these properties remove them.

  • Tabs

    • Tabs have been rewritten to use buttons instead of nav elements.
    • type now accepts contained (previously container) & line (previously default). This change is made to reflect the naming convention on carbondesignsystem.com.
    • ibm-tab-header component has been converted to a directive, hence a button with ibmTabHeader should be used.
    Old: New: 
    <ibm-tab-header-group type="container">
	<ibm-tab-header [paneReference]="content1">
		Content 1
	</ibm-tab-header>
</ibm-tab-header-group>

<ibm-tab #content1>
	Tab content 1
</ibm-tab>
    		 
    <cds-tab-header-group type="contained">
	<button cdsTabHeader [paneReference]="content1">
		Content 1
	</button>
</cds-tab-header-group>

<cds-tab #content1>
	Tab Content 1
</cds-tab>
    • You can now use the new TabSkeleton component with ibm-tab-header-group to indicate loading (With *ngIf, see storybook).

  • Theme (directive)

    • Directive that allows you to set the theme white, g10, g90, g100 to any element. All elements within the container will have the theme styles applied.
    • Theme resets the layer count to 1 (Starts from 0).
    • View storybook for more information.

  • Tile(s)

    • Theme has been marked as deprecated, use cdsLayer instead.
    • You no longer need to remember those long class names! Introduced fold directives for expandable tiles.
    • Expandable tile now supports interactive content. Simply set interactive to true.

  • Time picker & Time picker select

    • Now applies disabled styling to label text.
    • Theme has been marked as deprecated, use cdsLayer instead.
    • Added size input property which accepts sm, md, & lg.
      • All size classes are applied, including md (default).

  • Toggle

    • Toggle has been completely rewritten to improve accessibility & flexibility of layout
    • In previous version, <input type="checkbox"> was used, this has now been switched to <button role="switch">
    • ToggleChange class is now removed
    • change event has been removed, now use checkedChange (Same as checkbox) or simply double bind!
    Old: New: 
    <ibm-toggle (toggleChange)="func($event)" (change)="func($event)">
</ibm-toggle>
    		 
    <cds-toggle [(checked)]="checked" (checkedChange)="func($event)">
</cds-toggle>

  • Tooltip

    • Tooltips no longer support interactive content, use Toggletip for such situations. The API for tooltip has been updated & the component has been rewritten to use the Popover component/directive.
    • Unlike previously, triggers are predefined for all types of tooltip according to Carbon standards.
      • Tooltip opens on mouseenter (or programmatically)
      • Tooltip definition opens on mouse click (or programmatically)
      • Toggletip opens on mouse click (or programmatically)
    • API has been simplified and no longer need to add ibm-placeholder as all tooltip components are designed to be inline.
    Old: New: 
    <!-- Template for dynamic content-->
<ng-template #template let-tooltip="tooltip">
	<p>This is some tooltip text.</p>
	<div class="bx--tooltip__footer">
		<a href="/" class="bx--link">Learn More</a>
	</div>
</ng-template>

<div class="bx--tooltip__label">
	{{triggerText}}
	<span
		[ibmTooltip]="template"
		[offset]="offset"
		trigger="click"
		[placement]="placement">
		<div role="button">
			<svg ibmIcon="information--filled" size="16"></svg>
		</div>
	</span>
</div>
<ibm-placeholder></ibm-placeholder>
    		 
    <span cdsToggletipLabel>Toggletip label</span>
<cds-toggletip
[isOpen]="isOpen"
[align]="align"
(isOpenChange)="isOpenChange($event)">
	<button cdsToggletipButton>
		<svg ibmIcon="information--filled" size="16"></svg>
	</button>
	<!-- Dynamic content wrapper-->
	<div cdsToggletipContent>
		<p>This is some tooltip text.</p>
		<div class="bx--tooltip__footer">
			<a href="/" class="bx--link">Learn More</a>
		</div>
	</div>
</cds-toggletip>

    • Icon Tooltip - ibm-tooltip-icon (Removed)

      • Due to accessibility issues, this component has been removed.
      • You can use the new Tooltip or Icon button component as a replacement.
      Old: New: 
      	<ibm-tooltip-icon content="Setting">
		<svg>...</svg>
	</ibm-tooltip-icon>
      		 
      <cds-tooltip description="Setting">
	<svg>...</svg>
</cds-tooltip>

    • Tooltip Ellipses - ibmEllipsisTooltip - Removed

      • Use tooltip instead
      Old: New: 
      	<span
	class="ellipsis"
	ibmEllipsisTooltip>
		Tooltip for ellipsis because 
		I can and I am really really
		long
	</span>
	<ibm-placeholder></ibm-placeholder>
      		 
      <cds-tooltip
description="Tooltip for ellipsis because I can and I am really really long">
	<!-- Set style to make the text overflow -->
	<span class="overflowText">
		Tooltip for ellipsis because I can 
		and I am really really long
	</span>
</cds-tooltip>

    • Certain input properties (auto-align) will be available soon.

  • UI Shell

    • A lot of the accessibility issues have now been addressed with the shell!

    • Header Action (ibm-header-action)

      • Now uses icon buttons component, additional property bindings have been added to customize experience.
      • title property has been removed in favor of description

      Old:

      <ibm-header-action title="action"></ibm-header-action>

      New:

       <cds-header-action description="action"></cds-header-action>

Let us know if you run into any issues with the migration on Slack. We have a few things in the work to improve documentation & storybook experience.

Clone this wiki locally