Skip to content

iTwinUI v1 migration guide

Jump to bottom
Rohan edited this page Sep 24, 2024 · 38 revisions

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:

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.

General Changes

  • 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.
  • 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.

File Reference Changes

  • 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

HTML Changes

Alert

  • <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">

Avatar

  • <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

  • <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>

Dialog

  • 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

Header

  • <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>

Input

  • iui-textarea -> iui-input

Non-ideal state

  • 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>

Notification marker

  • <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>

Stepper

  • <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

Table

  • 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"

Tile

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

Workflow diagram

  • <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>

Visual Changes

Alert

  • Major visual changes have been made to meet accessibility requirements

Avatar

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

Button

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

Carousel

  • Carousel dots are now centered

Checkbox

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

Color picker

  • Slight visual changes as a result of a height change

Header

  • 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

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

Non-ideal state

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

Notification marker

  • Notification circle no longer has a colored background

Radio tile

  • 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

Side navigation

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

Slider

  • 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

Table

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

Tag

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

Tile

  • 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

Toast

  • Major visual changes have been made

Toggle switch

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

Tree

  • Tree is no longer transparent
Clone this wiki locally