FAQ - iTwin/iTwinUI GitHub Wiki

The base @itwin/itwinui-css package is meant to offer framework-agnostic component styling and a few global styles. It uses CSS variables defined in @itwin/itwinui-variables. The @itwin/itwinui-react package offers easy-to-use React components, based on the CSS and variables from @itwin/itwinui-css and @itwin/itwinui-variables.

In almost all cases, you probably want to install only @itwin/itwinui-react. Generally, there is no need to install @itwin/itwinui-variables or @itwin/itwinui-css unless you are using them standalone (without @itwin/itwinui-react). For more details about the relation between these packages, see the Styling documentation.

If your application has multiple dependencies which require different versions of iTwinUI-react, then you might need to do some extra work to make sure they are synced to the same version. This might involve force resolving versions if they are incompatible. See the section on version conflicts for more details.

Check out the following guides for detailed instructions. We also provide a semi-automated migration tool to make the process easier.

• v2 to v3 migration guide
• v1 to v2 migration guide

Webfont loading is a complex issue, so iTwinUI doesn't automatically load the recommended webfont (Noto Sans in v2, Open Sans in v1). There are many performance optimizations you might want to make, such as self-hosting, preloading, two-stage rendering, etc.

If you just need a quick way to get started (e.g. for prototyping), you can use Google Fonts. Add this to your entry-point:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@300;400;600;700&display=swap" rel="stylesheet">

If you know the url where the font is hosted, you can load it using <link rel="preload">. Combining this with the font-display property in your font-face will usually give you great performance.

Alternatively, you can also install the font as a dependency using Fontsource and import the necessary weights/styles in your entry point. Fontsource will declare the font-face for you, with font-display: swap and optimized unicode ranges.

import '@fontsource/noto-sans/300.css';
import '@fontsource/noto-sans/400.css';
import '@fontsource/noto-sans/600.css';
import '@fontsource/noto-sans/700.css';

Note that you will also need "Noto Sans Mono" if any of your components display monospace text.

Further reading:

• Optimize WebFont loading and rendering by Ilya Grigorik
• FontSource on Github
• A comprehensive guide to font loading strategies by Zach Leatherman
• The acceptable FOIT by Malthe Milthers

iTwinUI components only use these font weights: Light (300), Normal (400), Semi-Bold (600), Bold (700), and in some cases, Normal (400) italic. If you know the subset your application needs, you can customize it on your end (e.g. with Google Fonts or FontSource).

If you are not loading the Noto Sans or Open Sans webfont on your end, iTwinUI will fallback to the system fonts of the user's platform (e.g. Segoe UI in Windows and San Francisco in macOS).

You should already have this information somewhere, because you are expected to maintain your own state for the theme.

Your usage should look something like this:

const [theme, setTheme] = React.useState('dark'); // or store this in global state
<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

This can happen if the child component does not forward its ref (see docs). It can also happen if the child component is disabled. One workaround is to wrap your content in a div or span.

From 1.32.0 onwards, our popover gets appended to the document body, so this issue usually happens when it's nested inside another popover. The workaround is to use appendTo='parent' on the nested popover.

Prior to 1.32.0, our popover is appended to the parent container. This can cause issues if the parent container using CSS overflow or position: absolute or z-index stacking contexts. The workaround is to use appendTo={() => document.body}.

This could be because the popovers are nested in the react tree but siblings in the DOM. Try adding appendTo='parent' to the nested dropdown.

This is a tricky one depending on how your panel/modal is positioned. Try placing your panel or modal in a react portal. See more details in iTwin/iTwinUI-react#947. If that doesn't fix it, please open a new issue.

If you want your popover to be triggered on an element that is not a direct child, you can use the reference prop.

iTwinUI-react uses react-table v7, which can cause problems if your project is also using react-table v6. It can help to use custom aliases in package.json for both react-table v6 and its types:

...
"react-table-v6": "npm:react-table@^6.11.5"
...
"@types/react-table-v6: "npm:@types/react-table@^6.8.8"
...