Skip to content
This repository has been archived by the owner on Jan 5, 2023. It is now read-only.

iTwinUI react v2 migration guide

Jump to bottom
Mayank edited this page Dec 27, 2022 · 24 revisions
⚠️ Note: This page has moved to https://github.com/iTwin/iTwinUI/wiki/iTwinUI-react-v2-migration-guide

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 with the upcoming version 2. This includes things like component name changes, component structure changes, visual changes, file renames and moves, and deprecation. You can see the changes made to iTwinUI (CSS) recently for CSS v1 at the iTwinUI v1 migration guide. You can see the changes made to iTwinUI variables recently at the iTwinUI variables v1 migration guide.

  • 👁‍🗨 signifies a significant visual change
  • ❗ signifies a breaking change that must be updated by users

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

  • iTwinUI-react v2 depends on iTwinUI-CSS v1 (“@itwin/itwinui-css”: “1.x.x”) and on the illustrations package ("@itwin/itwinui-illustrations-react": "1.x.x") and the variables package ("@itwin/itwinui-variables": "1.x.x").
  • The dependency for the icons package ("@itwin/itwinui-icons-react") has been removed. SVGs are now accessed through the "icons" folder in the "utils" folder.

Theming

Components

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

Breaking Changes

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

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.

Home | FAQ

Clone this wiki locally