StrataKit theme bridge - iTwin/iTwinUI GitHub Wiki

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

Since StrataKit comes with a new visual language, iTwinUI v3 offers a theme bridge to make iTwinUI v3 components look similar to StrataKit components with minimal effort (no code changes required at individual component level). This way, existing iTwinUI-based applications can incrementally adopt StrataKit (or packages built using StrataKit) without any visual disharmony.

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

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 latest versions of the following packages:

Note

The theme bridge only needs to be set up by host applications. Individual packages that depend on @itwin/itwinui-react do not require any changes beyond ensuring that the package works with the latest stable version of @itwin/itwinui-react.

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 iTwinUI v3 <ThemeProvider> and the StrataKit <Root> component in your application entrypoint. The StrataKit <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 '@stratakit/foundations';

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

The StrataKit <Root> requires two props:

  • colorScheme: This should generally have the same value as the existing theme prop from the v3 <ThemeProvider>.
  • density: This currently only accepts a single value "dense".

It is also recommended to enable StrataKit's synchronizeColorScheme prop. This will help properly theme the popovers and other floating elements that are not DOM descendants of the root element.

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

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

Finally, activate the theme bridge in the v3 <ThemeProvider>.

  <ThemeProvider
    theme={theme}
+   future={{ themeBridge: true }} // or future={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 visual change is the green accent color (instead of blue).

⚠️ **GitHub.com Fallback** ⚠️