Skip to content

iTwinUI v5 theme bridge

Jump to bottom
Mayank edited this page Feb 25, 2025 · 13 revisions

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 new visual language, iTwinUI v3 offers 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.

The initial release of the theme bridge is focused on adjusting base colors and font. Over time, other visual aspects such as spacing may also be adjusted to match v5.

Important

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 use the theme bridge, you will need to install the following package versions:

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.2",
  "@itwin/itwinui-react-v5": "npm:@itwin/itwinui-react@5.0.0-alpha.6",
}

Usage

The theme bridge can be configured in the host application's entrypoint. This only needs to be done once and will be automatically inherited by all ThemeProviders in the tree, even across dependencies (assuming they all use the same instance of @itwin/itwinui-react v3).

To get started, set up both the v3 <ThemeProvider> and the v5 <Root> component in your application entrypoint. The v5 <Root> can be passed into the v3 <ThemeProvider>'s as prop to render a single DOM element.

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

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

To activate the theme bridge, use the future.themeBridge option from the v3 <ThemeProvider> component.

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

To control the theme, use the colorScheme prop from the v5 <Root>. This should generally have the same value as the existing theme prop from the v3 <ThemeProvider>.

It is also recommended to enable v5's synchronizeColorScheme prop to properly theme the popovers and other elements that are not DOM descendants of the root. Additionally, the v5 <Root> requires a density prop.

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

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

That's it! If all goes well, your application will now have a fresh look-and-feel without any component-level changes. The most noticeable change is the green accent color (instead of blue).

Clone this wiki locally