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 of the changes to @itwin/itwinui-css with version 1.0. This includes things like component name changes, component structure changes, visual changes, file renames and moves, and deprecation.

NOTE: The File Reference Changes and HTML Changes are breaking changes that must be updated by users.

• The @itwin/itwinui-css package is now CSS-only. Sass files are no longer part of the deliverable.
• A new @itwin/itwinui-variables package has been introduced to replace Sass variables. You can see the changes made to iTwinUI variables recently at the iTwinUI variables migration guide.
• Scoped themes support, allowing styling only part of the page or mixing themes in different parts of the page.
• We have officially ended support of Internet Explorer.
• The prioritized font has changed. The sans font now prioritizes 'Noto Sans' and the mono font now prioritizes 'Noto Sans Mono'. The previous fonts have not been deprecated. See the updated list here.
• Line height has changed from 22px to --iui-size-l (24px). This change visually affects most components.
• All four theme colors have been updated.
  • The base themes (light and dark) meet WCAG AA contrast score.
  • The high contrast themes (high contrast light and high contrast dark) meet WCAG AAA contrast score.
• Rounded corners in most components (using --iui-border-radius-1).
• More consistent elevation by ensuring lighter backgrounds (--iui-color-background) appear above darker ones (--iui-color-background-backdrop).
• Baseline height has increased by 1px, resulting in height changes in many components.
• Switched all sizes from px to rem to respect base font-size set in user preferences.

• inputs.css -> checkbox.css for Checkbox styling.
• inputs.css -> input.css for Input styling.
• inputs.css -> radio.css for Radio styling
• inputs.css -> select.css for Select styling
• inputs.css -> utils.css for other stylings
• icon.css -> utils.css
• notification-marker.css -> utils.css
• popover.css -> utils.css
• toast-notification.css -> toast.css
• user-icon.css -> avatar.css for Avatar styling
• wizard.css -> stepper.css for Stepper styling
• wizard.css -> workflow-diagram.css for Workflow diagram styling

• <div class="iui-alert iui-informational"> -> <div class="iui-alert" data-iui-status="informational"
• <div class="iui-alert iui-positive"> -> <div class="iui-alert" data-iui-status="positive"
• <div class="iui-alert iui-negative"> -> <div class="iui-alert" data-iui-status="negative"
• <div class="iui-alert iui-warning"> -> <div class="iui-alert" data-iui-status="warning"
• <div class="iui-alert iui-sticky"> -> <div class="iui-alert" data-iui-variant="sticky">
• <button class="iui-button iui-borderless iui-small> -> <button class="iui-alert-button">
• <svg class="iui-button-icon"> -> <svg class="iui-alert-button-icon">

• <span class="iui-user-icon"> -> <span class="iui-avatar">
• <div class="iui-user-icon-list"> -> <div class="iui-avatar-list">
• <span class="iui-user-icon iui-user-icon-count"> -> <span class="iui-avatar iui-avatar-count">

• <button class="iui-button iui-default"> -> <button class="iui-button">
• <button class="iui-button iui-dropdown"> -> <button class="iui-button iui-button-dropdown">
• <button class="iui-button iui-high-visibility"> -> <button class="iui-button" data-iui-variant="high-visibility">
• <button class="iui-button iui-cta"> -> <button class="iui-button" data-iui-variant="cta">
• <button class="iui-button iui-borderless"> -> <button class="iui-button" data-iui-variant="borderless">
• <button class="iui-button iui-idea"> -> <button class="iui-button" data-iui-variant="idea">
• <button class="iui-button iui-small"> -> <button class="iui-button" data-iui-size="small">
• <button class="iui-button iui-large"> -> <button class="iui-button" data-iui-size="large">
• <button class="iui-button iui-active"> -> <button class="iui-button" data-iui-active="true">
• <span class="iui-button-split-menu"> -> <span class="iui-button-split">
• <span class="iui-button-label"> -> <span>
• HTML structure change

<span class="iui-button-split">
-  <div>
	<button />
-  </div>
-  <div>
	<button />
-  </div>
</span>

• Backdrops with iui-backdrop should also use iui-backdrop-fixed (applies position: fixed) if the backdrop is full screen
• iui-dialog-wrapper has changed from position: relative to position: fixed
  • Adding data-iui-relative="true" to iui-dialog-wrapper gives it position: absolute

• <div class="iui-left"> -> <div class="iui-page-header-left">
• <div class="iui-center"> -> <div class="iui-page-header-center">
• <div class="iui-right"> -> <div class="iui-page-header-right">
• <div class="iui-header-logo"> -> <button class="iui-header-brand">
• <svg class="iui-header-button-icon"> -> <svg class="iui-header-brand-icon">
• <span class="iui-label"> -> <span class="iui-header-brand-label">
• <div class="iui-divider"> -> <div class="iui-page-header-divider">
• <button class="iui-button iui-borderless iui-header-button iui-header-dropdown-button"> -> <button class="iui-header-breadcrumb-button">
• <svg class="iui-button-icon iui-header-button-icon"> -> <svg class="iui-header-breadcrumb-button-icon">
• <svg class="iui-button-icon"> -> <svg class="iui-header-breadcrumb-button-dropdown-icon">
• <nav> -> <nav class="iui-header-breadcrumbs">
• <ol class="iui-header-breadcrumbs-list"> and <li class="iui-header-breadcrumb-item"> have been added
• HTML structure change:

  - <svg-chevron-right class="iui-chevron"></svg-chevron-right>
  + <li class="iui-breadcrumbs-separator">
  +	 <svg-chevron-right></svg-chevron-right>
  + </li>

  - <span>
  - 	<div>Label</div>
  - 	<div class="iui-description">Sublabel</div>
  - </span>
  + <span class="iui-header-breadcrumb-button-text">
  + 	<span class="iui-header-breadcrumb-button-text-label">Label</span>
  + 	<span class="iui-header-breadcrumb-button-text-sublabel">Sublabel</span>
  + </span>

• iui-textarea -> iui-input

• HTML structure change:

  <div class="iui-non-ideal-state">
  +	<div class="iui-non-ideal-state-illustration">
  -		<svg class="iui-non-ideal-state-illustration"></svg>
  +		<svg></svg>
  +	</div>
  </div>

• <svg class="iui-notification-primary"> -> <span class="iui-notification-marker">
• <svg class="iui-notification-positive"> -> <span class="iui-notification-marker" data-iui-variant="positive">
• <svg class="iui-notification-warning"> -> <span class="iui-notification-marker" data-iui-variant="warning">
• <svg class="iui-notification-negative"> -> <span class="iui-notification-marker" data-iui-variant="negative">
• <svg class="iui-urgent"> -> <span data-iui-urgent="true">
• HTML structure change:

  +	<span class="iui-button-icon iui-notification-marker" aria-hidden="true">
  -		<svg class="iui-button-icon iui-notification-primary"></svg>
  +		<svg></svg>
  +	</span>

• <div class="iui-wizard"> -> <div class="iui-stepper">
• <li class="iui-wizard-step"> -> <li class="iui-stepper-step">
• <div class="iui-wizard-step-name"> -> <div class="iui-stepper-step-name">
• <div class="iui-wizard-track-content"> -> <div class="iui-stepper-track-content">
• <span class="iui-wizard-circle"> -> <span class="iui-stepper-circle">
• <div class="iui-wizard-steps-label"> -> <div class="iui-stepper-steps-label">
• <span class="iui-steps-count"> -> <span class="iui-stepper-steps-label-count">
• iui-long no longer necessary

• Row
  • iui-row -> iui-table-row
• Expandable Row
  • iui-row-expander -> iui-table-row-expander
  • iui-row-expanded -> iui-table-row-expanded
  • iui-expanded-content -> iui-table-expanded-content
• Cell
  • iui-cell -> iui-table-cell
  • iui-cell-end-icon -> iui-table-cell-end-icon
• Sticky Columns
  • iui-cell-sticky -> iui-table-cell-sticky
  • iui-cell-shadow-left -> iui-table-cell-shadow-left
  • iui-cell-shadow-right -> iui-table-cell-shadow-right
• Resizer
  • iui-resizer -> iui-table-resizer
  • iui-resizer-bar -> iui-table-resizer-bar
• Paginator
  • iui-paginator -> iui-table-paginator
  • iui-paginator-pages-group -> iui-table-paginator-pages-group
  • iui-paginator-page-button -> iui-table-paginator-page-button
  • iui-paginator-page-button-small -> iui-table-paginator-page-button-small
  • iui-paginator-ellipsis -> iui-table-paginator-ellipsis
  • iui-paginator-ellipsis-small -> iui-table-paginator-ellipsis-small
  • iui-paginator-page-size-label -> iui-table-paginator-page-size-label
• Column Reorder
  • iui-reorder-column-left -> iui-table-reorder-column-left
  • iui-reorder-column-right -> iui-table-reorder-column-right
  • iui-reorder-bar -> iui-table-reorder-bar
• Sort
  • iui-sort -> iui-table-sort
• Filter
  • iui-filter-button -> iui-table-filter-button
  • iui-column-filter -> iui-table-column-filter
• More Options
  • iui-more-options -> iui-table-more-options
• Aria Attributes
  • iui-selected -> aria-selected="true"
  • iui-disabled -> aria-disabled="true"
  • aria-multiselectable="true" has been added to iui-table-body elements for tables that allow multiple row selection
• Date Attributes
  • iui-condensed -> data-iui-size="condensed"
  • iui-extra-condensed -> data-iui-size="extra-condensed"
  • iui-positive -> data-iui-status="positive"
  • iui-negative -> data-iui-status="negative"
  • iui-warning -> data-iui-status="warning"
• Other
  • <svg>s for iui-table-cell-end-icon no longer need class="iui-button-icon"

• <div class="iui-tile iui-progress"> -> <div class="iui-tile iui-loading">

• <div class="iui-wizard iui-workflow"> -> <div class="iui-workflow">
  • Workflow diagram HTML structure

  <ol class="iui-workflow-diagram">
    <li class="iui-workflow-diagram-step">
  	<span class="iui-workflow-diagram-content">Start</span>
    </li>
  </ol>

• Major visual changes have been made to meet accessibility requirements

• Slight visual changes as a result of setting the default box-sizing property to border-box

• Slight visual changes as a result of a line-height change

• Carousel dots are now centered

• Loading and disabled state visual stylings are now unified across checkbox, table, and tile
• Slight visual change to outline-width

• Slight visual changes as a result of a height change

• outline added to header button thumbnails
• box-shadow added to header menu item thumbnails
• Slight visual changes as a result of setting the default box-sizing property to border-box

• Menu max height has changed to be relative to menu item height

• Slight visual changes as a result of setting the default box-sizing property to border-box

• Notification circle no longer has a colored background

• Radio tile border will see slight visual changes if stacked vertically
• Slight visual changes as a result of setting the default box-sizing property to border-box

• Slight visual changes as a result of the side navigation button strip appearing above the border

• Min and max slider labels are in-line with the rail on the same axis and have a min-width/height for horizontal/vertical sliders respectively
• Slight visual changes as a result of setting the default box-sizing property to border-box

• Loading and disabled state visual stylings are now unified across checkbox, table, and tile

• Slight visual changes as a result of setting the default box-sizing property to border-box

• Loading and disabled state visual stylings are now unified across checkbox, table, and tile
• Slight visual changes as a result of setting the default box-sizing property to border-box

• Major visual changes have been made

• Slight visual changes as a result of setting the default box-sizing property to border-box

• Tree is no longer transparent