iTwinUI v5 theme bridge

This document describes how you can make use of the new theme from iTwinUI v5 within an existing application that's built using iTwinUI v3.

Since iTwinUI v5 has a different visual language than iTwinUI v3, we have created a theme bridge to make existing iTwinUI v3 components look similar to iTwinUI v5 components with minimal effort. This way, existing iTwinUI v3 applications can add iTwinUI v5 components without any visual disharmony; the theme bridge ensures that iTwinUI v3 components closely match the iTwinUI v5 visual language.

Note

Before getting started, make sure your application is using iTwinUI v3. If any of your components (or your dependencies) are still using iTwinUI v2, they will need to be migrated to iTwinUI v3 first.

Installation

To try out the theme bridge, you will need to install the following package versions:

• @itwin/[email protected]
• @itwin/[email protected]

Since both of these are published under the same package name, you will need to use npm aliases to be able to install them in the same application. e.g.:

"dependencies": {
  "@itwin/itwinui-react": "3.17.0-dev.1",
  "@itwin/itwinui-react-v5": "npm:@itwin/[email protected]",
}

Usage

To make use of the theme bridge, you need to set up the v3 <ThemeProvider> and the v5 <Root> component in your application entrypoint. Make sure to wrap v3's <ThemeProvider> with v5's <Root> component and not the other way around.

import { ThemeProvider } from '@itwin/itwinui-react';
import "@itwin/itwinui-react/styles.css";
import { Root } from '@itwin/itwinui-react-v5/bricks';

const App = () => (
  <Root>
    {/* Any iTwinUI v5 components */}
    
    <ThemeProvider>
      {/* Any iTwinUI v3 or v5 components */}
    </ThemeProvider>
  </Root>
);

To activate the theme bridge, you need to use the future.themeBridge option in the v3 <ThemeProvider> component.

  <ThemeProvider
+   future={{ themeBridge: true }}
  >
    {/* … */}
  </ThemeProvider>

To control the theme, you need to pass the colorScheme prop to the v5 <Root> and the theme prop to the v3 <ThemeProvider>.

+ const [theme, setTheme] = useState<'light' | 'dark'>('light');

  <Root
+   colorScheme={theme}
    density='dense'
  >
    <ThemeProvider
+     theme={theme}
      future={{ themeBridge: true }}
    >
      {/* … */}
    </ThemeProvider>
  </Root>