Skip to content
This repository has been archived by the owner on Jan 5, 2023. It is now read-only.

FAQ

Jump to bottom
Vilius edited this page Feb 3, 2022 · 26 revisions

Don't see your problem listed here? You can create a discussion or issue.

General

iTwinUI packages

What is the difference between iTwinUI-css and iTwinUI-react? Do I need one or both?

The base iTwinUI-css package is meant to offer framework-agnostic component styling, as well as Sass variables for spacing, color, etc.

The iTwinUI-react package depends on and uses styles from the base iTwinUI-css package to offer React components.

In most cases, you will be able to just install iTwinUI-react to use the components, and still be able to use the variables from iTwinUI-css (through transitive dependency).

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

Fonts

My project is not using the recommended Open Sans by default.

Webfont loading is a complex issue, so iTwinUI doesn't automatically load the Open Sans webfont. 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=Open+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/open-sans/300.css';
import '@fontsource/open-sans/400.css';
import '@fontsource/open-sans/600.css';
import '@fontsource/open-sans/700.css';

Further reading:

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

What if I want to customize the loading/rendering of my webfont?

You can observe the loading of your fonts using the Font Loading API (or with FontFaceObserver), and only enable the Open Sans font family when you want.

iTwinUI offers partial support for this using the iui-font-family Sass mixin and $iui-font-loaded-class Sass variable. You should include this mixin in your body and set the value of this variable to the name of a class that can you apply to body when fonts finish loading. Example:

// In your scss
@import '@itwin/itwinui-css/scss/style/index';
$iui-font-loaded-class: fonts-loaded; // name of custom class
body {
  @include iui-font-family;
}
// In your font loading JS
const font = new FontFace('Open Sans', 'url(/assets/Open-Sans.woff2)');
await font.load();
document.fonts.add(font);
document.body.classList.add('fonts-loaded'); // use the name you set in your scss

When defining FontFace using this approach, you can add optional descriptors (e.g. weight) and additional source urls (e.g. local or woff) similar to font-face in CSS.

Further reading:

Why does my app font look different on different devices?

If you are not loading the 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).

Components

ThemeProvider / useTheme

How do I get access to the current theme?

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

Despite its name, ThemeProvider does not currently use the context API. And useTheme does not return the currently used theme. Both of them just set the right classes to make theme switching work.

Your usage should look something like this:

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

Popover (tooltips, dropdowns, etc)

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.

This can happen due to the parent container using CSS overflow or position: absolute or z-index stacking contexts. (By default, Tooltip is appended to the parent container.) 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.

Table

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

Home | FAQ

Clone this wiki locally