iTwinUI css v2 migration guide - iTwin/iTwinUI GitHub Wiki

Semi-Automated Migration Tool 🤖

To help with the migration, we also provide a semi-automated migration tool that scans your project repo for old code and recommends replacements.

Download options:

• Clone iTwinUI-migration-tool GitHub repo (recommended)
• Download zip file (version: 08 May 2025) with the tool (for users outside the iTwin GitHub org)

---

This wiki page documents all breaking changes in @itwin/[email protected].

Also see: @itwin/[email protected] migration guide.

• #1270: Change line-height to use a unitless value.
• #1302: border-box will now be set for all elements under iui-root.
• #1373: Converted all physical CSS properties to their logical equivalents.

• #1247: Removed the use of iui-alert-icon, iui-alert-button, and iui-alert-button-icon

  - class="iui-alert-icon"
  + class="iui-svg-icon"
  + data-iui-icon-color="status" // where "status" is informational, positive, negative, or warning

  - class="iui-alert-button"
  + class="iui-button"
  + data-iui-variant="borderless"
  + data-iui-size="small"

  - class="iui-alert-button-icon"
  + class="iui-button-icon"

• #1446: iui-avatar has been refactored to be a single <span>, and the status is now applied using the data-iui-status attribute. The colors have been updated to pass AAA contrast ratio.

• #1369: The iui-breadcrumbs-item-overrides class name has been removed. Breadcrumbs items now use the iui-breadcrumbs-content class name.

    <a
  -   class="iui-breadcrumbs-text"
  +   class="iui-breadcrumbs-content"
      href="#"
    >
      Anchor
    </a>

  - <span class="iui-breadcrumbs-text">Span</span>
  + <span class="iui-breadcrumbs-content">Span</span>

    <button
      type="button"
  -   class="iui-breadcrumbs-button"
  +   class="iui-breadcrumbs-content"
    >
  -   <span class="iui-breadcrumbs-text">
  +   <span>
        Button
      </span>
    </button>

• #1556: Items inside button-group no longer need a wrapping <div>.

    <div class="iui-button-group">
  -   <div>
        <button>...</button>
  -   </div>
  -   <div>
        <button>...</button>
  -   </div>
    </div>

• #1559: Changed iui-button-group-vertical class to iui-button-group with attribute data-iui-orientation="vertical".

  -  <div class="iui-button-group-vertical">
  +  <div class="iui-button-group" data-iui-orientation="vertical">
      ...
    </div>

• #1489: --iui-color-dot-inset has been split into --iui-color-dot-inset-block and --iui-color-dot-inset-inline.

• #1269: All dialog variants have flex applied by default. This means the content should be wrapped with iui-dialog-content for optimal layout.

• #1354: The following class names have been updated:

  - class="iui-header"
  + class="iui-expandable-header"

  - class="iui-icon"
  + class="iui-expandable-block-icon"

  - class="iui-title"
  + class="iui-expandable-block-title"

  - class="iui-caption"
  + class="iui-expandable-block-caption"

  iui-expanded, iui-small and iui-borderless have been removed and replaced with data attributes:

  - class="iui-expanded"
  + data-iui-expanded={true}

  - class="iui-small"
  + data-iui-size="small" //or "default"

  - class="iui-borderless"
  + data-iui-variant="bordereless" //or "default"

• #1355: iui-input-container class was removed, in favor of iui-input-grid.

• #1529: Location marker styles are no longer offered.

• #1295: iui-menu-item and iui-menu-description classes were removed, in favor of iui-list-item and iui-list-item-description.
• #1577: iui-scroll class was removed; menus are scrollable by default.

• #1356: iui-progress-radial has been refactored to be a single <div> instead of using a nested svg. Size and status have been moved to data attributes. Also it is recommended to explicitly set size when using in other components.

• #1370: iui-progress-indicator-linear has been refactored to be a single <div>. Size, status, indeterminate variant, animation, etc are now specified using data attributes.

• #1420: Removed <div class="iui-radio-tile-content">. Also, data-iui-disabled attribute must be set on the radio-tile for browsers that don't support :has(:disabled) (firefox).

   <label
     class="iui-radio-tile"
  +  data-iui-disabled="true"
   >
     <input class="iui-radio-tile-input" type="radio" disabled />
  -  <div class="iui-radio-tile-content">
       <svg class="iui-radio-tile-icon">...</svg>
       <div class="iui-radio-tile-label">...</div>
       <div class="iui-radio-tile-sublabel">...</div>
  -  </div>
   </label>

• #1328: iui-progress-overlay has been renamed to iui-overlay and moved to overlay.scss

• #1548: Using aria-selected instead of iui-active in Tabs to set active styling.
• #1548: Combined tabs stripe variables: --iui-stripe-left and --iui-stripe-top into --iui-tabs-stripe-position; --iui-stripe-width and --iui-stripe-height into --iui-tabs-stripe-size.
• #1548: data-iui-scroll-placement attributes in Tabs were removed. Updated tabs start and end masks to be applied on scroll animation.
• #1548: The iui-tabs element has changed from <ul> to <div>. iui-tabs children are no longer wrapped in an <li> element.
• #1548: The iui-tab-label wrapper class has been removed. The iui-tab-label class now applies to the <span> which holds the tab's label. iui-tab-description is now a <span> element.

• #1322: Removed input-container code from utils.css in favor of input-container.css.