iTwinUI react v2 migration guide - iTwin/iTwinUI GitHub Wiki

Semi-Automated Migration Tool πŸ€–

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

Download options:

This wiki page is to document all of the changes occurring to iTwinUI-react v2. This includes things like component name changes, component structure changes, visual changes, file renames and moves, and deprecation.

  • πŸ‘β€πŸ—¨ signifies a significant visual change
  • ❗ signifies a breaking change that must be updated by users

There are also migration guides available for the other two iTwinUI packages:

General

  • We have officially ended support of Internet Explorer. If you still need IE support, please contact the team or make an issue.
  • πŸ‘β€πŸ—¨ 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.

Dependencies

As of the latest 2.x version, iTwinUI-react no longer depends on: @itwin/itwinui-icons-react, @itwin/itwinui-css, @itwin/itwinui-variables.

  • iTwinUI components that internally need SVGs will inline them. If you need to use one of our icons in your app, please manually install the latest @itwin/itwinui-icons-react package.
  • Prior to v2.12.0, iTwinUI-react had direct dependencies on @itwin/itwinui-css@1.x, @itwin/itwinui-variables@2.x. In v2.12.0, these dependencies were removed, and the CSS produced by both of these packages is inlined into iTwinUI-react.
  • @itwin/itwinui-illustrations-react is only used in the now-deprecated ErrorPage and will be removed in the next major version. If you need to use the illustrations standalone, please install the package manually. If you are using ErrorPage, please consider using NonIdealState instead.

Theming

  • The theming method using useTheme has been deprecated. Please use ThemeProvider instead. Instructions can be found in the README.

Incremental migration

It may not be feasible for your app to upgrade entirely to iTwinUI v2 all at once. To alleviate this, we have added the ability to incrementally migrate to v2 for parts of your app, while still using v1 for the rest of the page.

To use this feature, make sure all parts that use v1 are updated to at least @itwin/[email protected] - you might need (p)npm overrides to do this. Then install @itwin/[email protected] (or later), and wrap your v2 parts in ThemeProvider.

<body>
  <!-- rest of your app (v1) -->

  <ThemeProvider>
    <!-- new UI built using v2 -->
  </ThemeProvider>
</body>

Packages

When designing a package that uses iTwinUI v2 but is intended to be used by apps that might still be using iTwinUI v1 elsewhere, make sure to wrap all entrypoints of your package with <ThemeProvider theme='inherit'>.

<ThemeProvider theme='inherit'>
  <!-- package entrypoint -->
</ThemeProvider>

For more details and a demo, see "iTwinUI 1.x and 2.x coexisting".

Relative font size

iTwinUI now uses rem units instead of px for spacing. Doing this allows the components to automatically scale with the base font size specified by the end user's operating system and/or browser settings. However, for this to work, your page must not use a constant pixel value for the font-size of the root element.

html {
  font-size: 14px; // ❌ don't do this
}

If there is a font-size already set on the root element (perhaps through some third-party styles), then you can unset it or use 100%.

html {
  font-size: 100% !important;
}

And if you would like to control the size of most text on the page, you can still do so by setting it on the body, as it will get inherited by every element on the page.

body {
  font-size: 0.875rem;
}

Components

To see examples of the components, visit the storybook page.

Breaking Changes

  • Table
    • ❗ The formatting for the table header has changed. The first level header should be removed from a table's column definition.
      • Previous format: [{ Header: '', columns: [ ...columns info... ] }]
      • New format: [ ...columns info... ]
    • The old format will also continue to work if you update to version 2.5.0 or later.
  • Alert
    • ❗ The previously deprecated property onClick has been removed and can no longer be used. Instead, use clickableTextProps.
  • Tab (singular)
    • ❗ The previously deprecated HorizontalTab has been removed and can no longer be used. Use Tab instead.
    • ❗ The previously deprecated HorizontalTabProps has been removed and can no longer be used. Use TabProps instead.
  • Checkbox and Radio
    • ❗ The previously deprecated property checkmarkClassName has been removed and can no longer be used. This is applied on the actual checkbox/radio <input> element. The checkmark has been moved into a pseudo-element.
    • ❗ The previously deprecated property checkmarkStyle has been removed and can no longer be used. This is applied on the actual checkbox/radio <input> element. The checkmark has been moved into a pseudo-element.

Deprecations

  • Header
    • The property userIcon has been deprecated. Avatars (previously user icons) can now be part of the actions property list.
  • ErrorPage has been deprecated and is now called NonIdealState. Using NonIdealState instead of ErrorPage allows the client bundle to be smaller, as it doesn't have to import all of the images used in ErrorPage. Note that NonIdealState has been completely reworked to achieve this goal. Rather than using the property errorType to select what type of image to show, use the property svg to apply the image of your choosing.
    • ErrorPage > NonIdealState
    • ErrorPageProps > NonIdealStateProps
    • ErrorPageTypes has been deprecated.
    • ErrorTypeTranslations has been deprecated.
  • Tabs (plural, container) - HorizontalTabs and VerticalTabs have been deprecated. Use Tabs with the appropriate properties.
    • HorizontalTabs > Tabs (defaults to horizontal, but can also use property orientation = 'horizontal')
    • VerticalTabs > Tabs with property orientation = 'vertical'
    • HorizontalTabsProps and VerticalTabsProps > TabsProps
  • Theming
    • ownerDocument has been deprecated from ThemeOptions. Render ThemeProvider in the correct document instead.
  • Typography - Several text components have been deprecated. Use Text with the appropriate properties.
    • Headline > Text with property variant = 'headline'
    • Title > Text with property variant = 'title'
    • Subheading > Text with property variant = 'subheading'
    • Leading > Text with property variant = 'leading'
    • Body > Text with property variant = 'body'
    • Small > Text with property variant = 'small'
  • UserIcon has been deprecated and is now called Avatar.
    • UserIcon > Avatar
    • UserIconProps > AvatarProps
    • UserIconStatus > AvatarStatus
  • UserIconGroup has been deprecated and is now called AvatarGroup.
    • UserIconGroup > AvatarGroup
    • UserIconGroupProps > AvatarGroupProps
  • Wizard has been deprecated and is now separated into Stepper and WorkflowDiagram. Stepper is used for the β€˜basic’ and β€˜long’ types of wizard. WorkflowDiagram is used for the β€˜workflow’ type of wizard. Continue using property type for Stepper. WorkflowDiagram has no property type as there is only one type – workflow.
    • Wizard > Stepper or WorkflowDiagram
    • WizardProps > StepperProps orWorkflowDiagramProps
    • WizardLocalization > StepperLocalization

Code Structure Changes

  • Alert
    • The html formatting has changed for the close button. Previously the close button was composed of an IconButton, but is now made with <button/>. Additionally, the icon now has the class name 'iui-alert-button-icon'.
  • Button
    • The class name "iui-button-label" has been removed from the span that surrounds a button's children.
    • Button no longer passes class names to startIcon and endIcon.
  • ComboBox
    • The virtualized combobox menu now applies a class name of 'iui-scroll' to the menu. This is also where class names can now be applied to the virtualized combobox menu.
  • Header
    • The html formatting has changed for the header's breadcrumbs. The breadcrumbs are now represented as <li/> and are surrounded by a container <ol/>.
  • IconButton
    • IconButton no longer passes class names to icon.
  • SplitButton
    • The html formatting has changed. Previously SplitButton was formatted with <span> <div> <Button/> </div> <div> <DropdownMenu/> </div> </span> but now the divs have been dropped so that the formatting is now <span <Button/> <DropdownMenu/> </span>.

Significant Visual Changes

  • πŸ‘β€πŸ—¨ Alert: Visuals have changed to meet accessibility requirements. Sticky alert is now offset from top and sides of the window.
  • πŸ‘β€πŸ—¨ SideNavigation: Visuals have changed.
  • πŸ‘β€πŸ—¨ Table, Checkbox, & Tile: Visual styling for disabled and loading are now the same across Table, Checkbox, and Tile.
  • πŸ‘β€πŸ—¨ Toast: Visuals have changed.
  • πŸ‘β€πŸ—¨ Tree: No longer transparent and has a background.

Added Features

  • Table
    • Added property isLoading to table rows.
    • Added counter to paginated tables that shows how many rows have been selected if multi-selection mode is enabled.
    • Updated keyboard navigation support for sorting and filtering.
  • Tile
    • Added properties status, isLoading, and isDisabled to tile.
⚠️ **GitHub.com Fallback** ⚠️