Migrating to V3 - Intelligence Community Design System

Show navigation section

Introduction

ICDS V3 introduces one of our mostly highly anticipated features, dark mode, as well as general improvements. This is a comprehensive guide on how to upgrade your V2 app to V3. For a full list of the changes made in V3, please read the changelog .

Theming and dark mode

With V3's arrival comes an improvedic-theme component. This component was initially responsible for managing the theme of the UI Kit. In addition to the existing functionality, you can now use theic-theme component to set whether a component responds to changes in the system's light and dark theme or whether it always appears in a particular mode. Guidance on implementing theic-theme component can be found in the custom theme guidance .

Codemod

To aid your migration from ICDS V2 to V3, we have created a codemod to automate the process of migrating your code. A codemod is a tool that can be used to make large-scale changes to codebases quickly and efficiently. Our ICDS V2 to V3 codemod is the simplest and easiest way to migrate your codebase to the latest version of the UI Kit.

How it works

Given a directory, it will scan over files and find any relevant ICDS components that require a change either by component name or props used.

How to run

This package works as an executable requiring a directory and optional test boolean argument to help migrate your tests from ICDS V2 to ICDS V3. Further information and examples can be found in the codemod package README .

- npm i @ukic/react
- npm i @ukic/web-components
- npx @ukic/codemod <dir> <test>

Breaking changes

1. Prop renaming

Theappearance prop has been replaced with thetheme andmonochrome props .
Inic-text-field (IcTextField ) theauto-focus prop has been renamed toautofocus and themax-length/maxLength prop has been renamed tomax-characters/maxCharacters .
Thecolor prop inic-hero (IcHero ),ic-top-navigation (IcTopNavigation ),ic-side-navigation (IcSideNavigation ),ic-footer (IcFooter ) andic-theme (IcTheme ) has been renamed tobrand-color/brandColor .
Thegroup-title/groupTitle prop inic-accordion-group (IcAccordionGroup ) andic-footer-link-group (IcFooterLinkGroup ) has been renamed tolabel .
Thetext-label/textLabel prop inic-badge (IcBadge ) has been renamed tolabel .
Thebody-max-lines/bodyMaxLines prop inic-empty-state (IcEmptyState ) has been renamed tomax-lines/maxLines .
Theerror prop inic-input-label (IcInputLabel ) has been renamed tostatus witherror as an option.
Theboundary-count/boundaryCount andadjacent-count/adjacentCount props inic-pagination (IcPagination ) have been renamed toboundary-page-count/boundaryPageCount andadjacent-page-count/adjacentPageCount .
Thedisable-filter/disableFilter prop inic-search-bar (IcSearchBar ) andic-select (IcSelect ) has been renamed todisable-auto-filtering/disableAutoFiltering .
Thehint-text/hintText prop inic-search-bar (IcSearchBar ) has been renamed toassistive-hint-text/assistiveHintText .
Someic-step (IcStep ) props have had the prefix "step" removed, e.g.,step-status/stepStatus has been renamed tostatus ,step-title/stepTitle andstep-subtitle/stepSubtitle props have been renamed toheading andsubheading respectively.
Thetoggle-checked/toggleChecked prop inic-toggle-button (IcToggleButton ) has been renamed tochecked .
Thesmall=”true” prop has been replaced withsize=”small” inic-select (IcSelect ).
Thetheme prop has been renamed tobrand inic-theme (IcTheme ).
Thekeyboard-shortcut/keyboardShortcut prop has been renamed tokeyboard-shortcut-label/keyboardShortcutLabel inic-menu-item (IcMenuItem ).
Thebuttons prop inic-dialog , which defaulted totrue , has been renamed tohide-default-buttons/hideDefaultButtons , with a default value offalse .

2. Component renaming

ic-card (IcCard ) has been renamed toic-card-vertical (IcCardVertical ) .
ic-data-entity (IcDataEntity ) has been renamed toic-data-list (IcDataList ).

3. Removed props/slots/events/methods

Deprecated props, slots, events, and methods have been removed entirely.
Themax-length/maxLength andmax-length-message/maxLengthMessage props have been removed fromic-text-field (IcTextField ). Instead, use themax-characters/maxCharacters prop and thehide-char-count/hideCharCount prop to hide the character count visually. It is not possible for the input to exceed the number of characters provided via themax-characters/maxCharacters prop.
Thesmall prop has been removed. Please usesize="small" instead.
Thesize=”default” prop has been removed. Please usesize="medium" instead.
Thebuttons prop foric-dialog (IcDialog ) has been removed. Please use the newhide-default-controls/hideDefaultControls prop (This new prop defaults tofalse ).
Thebutton-props/buttonProps prop has been removed from theic-dialog (IcDialog ) component and replaced with thedialog-controls slot.
Theshow-state/showState prop has been removed from theic-switch (IcSwitch ) component.
Form props (formaction ,formenctype ,formmethod ,formnovalidate , andformtarget ) have been removed fromic-checkbox (IcCheckbox ),ic-radio-option (IcRadioOption ) andic-select (IcSelect ).

4. Class name changes

Class names on the host for most components have been updated to include the component name in the class name. For example,disabled has been updated toic-select-disabled .
Other class names have also changed and may affect current tests.

5. Event name changes

TheicThemeChange event has been renamed toicBrandChange .
The eventssideNavExpanded andtopNavResized are now calledicSideNavExpanded andicTopNavResized .

6. CSS token changes

Some existing CSS tokens have been renamed following the move towards primitive, semantic, and component tokens.

7. Component behaviour changes

Theic-toast (IcToast ) component now shows a dismiss button when the toast is hovered over or focused.
The shadow DOM has been removed fromic-radio (IcRadio ) and may affect current tests.
ic-select-with-multi (IcSelectWithMulti ) is no longer a standalone component. The multi-select functionality can now be achieved using theic-select (IcSelect ) component and itsmultiple prop.
Theic-select (IcSelect ) component's searchable variant now clears the input field when it loses focus if the value does not match any of the items in the list of options.
Theic-select (IcSelect ) component'sonIcChange/icChange event is no longer emitted on each keystroke or controlled by thedebounce prop. TheonIcInput/icInput event should be used for handling changes based on keystrokes and is controlled by thedebounce prop.
Theic-select (IcSelect ) component'sonIcChange/icChange event now emits a value of typestring | string[] | null . Previously the value was of typestring .
Theic-loading-indicator (IcLoadingIndicator ) component'slabel prop now dynamically changes the label value by passing an array of strings, instead of a string separated by/ . For example,["Loading", "Still loading"] .
The<a> used internally withinic-footer-link (IcFooterLink ) has been replaced with<ic-link> and may affect current tests.
The heading hierarchy withinic-hero (IcHero ) has been updated, which may affect accessiblity compliance. Theheading prop is now semantically ah2 element, and thesecondary-heading/secondaryHeading prop is now semantically ah3 element.
The hidden input has been removed fromic-radio-group (IcRadioGroup ) and may affect current tests.

// v2
<ic-select-with-multi
  id="select-default"
  label="What are your favourite types of coffee?"
  multiple="true"
></ic-select-with-multi>
// v3
<ic-select
  id="select-default"
  label="What are your favourite types of coffee?"
  multiple="true"
></ic-select>

New features

1. Theme prop

A newtheme prop has been added to many components to enable light and dark mode.

2. Monochrome prop

A newmonochrome prop has been added to many components.

Manual migration steps

Update Prop Names : Replace all instances of the old prop names with the new ones.
Update Component Names : Rename components according to the new names.
Remove Deprecated Props/Slots/Events/Methods : Remove any usage of deprecated props, slots, events, and methods.
Update Class Names : If you use class names to reference elements in tests, then update class names to the new format.
Update Event Names : Replace old event names with the new ones.
Update CSS Tokens : Update any CSS tokens that have been renamed.
Test Your Application : Thoroughly test your application to ensure that all changes have been applied correctly and that there are no regressions.

By following these steps, you should be able to successfully migrate your project from version 2 to version 3 of the@ukic/web-components or@ukic/react package.

Last reviewed 23 April 2025 .