-
Notifications
You must be signed in to change notification settings - Fork 23
FAQ
What is the difference between iTwinUI-css, iTwinUI-variables and iTwinUI-react? Which one should I install?
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 builds upon the CSS from @itwin/itwinui-css to offer easy-to-use React components.
In most cases, you will be able to just install @itwin/itwinui-react to use the components, and still be able to use the CSS variables from @itwin/itwinui-variables. You can also add @itwin/itwinui-variables as a dependency on your end but you need to make sure to dedupe it so your lockfile only has one version of it.
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.
My project is not using the recommended font by default.
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
Which font styles/weights do I need?
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).
Why does my app font look different on different devices?
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).
How do I get access to the current theme?
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>Our popover components wrap an external library called tippy.js. We recommend going through their documentation if you have trouble using them.
My tooltip does not show up on hover.
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.
My tooltip/dropdown appears cut off or beneath other elements.
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}.
I want to show my tooltip on a different element.
If you want your popover to be triggered on an element that is not a direct child, you can use the reference prop.
Our table is a styled wrapper around react-table. We recommend going through their documentation and issues before opening new issues in iTwinUI-react.
Conflicts with react-table v6
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"
...