Styling - iTwin/iTwinUI GitHub Wiki

This guide is designed to help you understand iTwinUI's styling approach and how you can make best use of it as a consumer of iTwinUI.

Cascade layers

As of August 2023, iTwinUI makes use of cascade layers in all three major versions. Layers are a powerful, well-supported browser feature that help control the order in which CSS is applied (regardless of order of imports or selector specificity). In practice, here's what it means for you:

If you're not using cascade layers elsewhere, then all your styles are considered "unlayered" and will win over any layered styles from iTwinUI. While we do not recommend heavily overriding iTwinUI styles all over your application, we do recognize that there are legitimate reasons to do this. Using layers in iTwinUI gives you the final say and avoids specificity battles. Hacks like !important are no longer necessary.

If you have a global style "reset" or "normalizer", then you might see some unexpected results, as your global styles would always win over any iTwinUI styles. We recommend placing such global styles in your own layer and placing this layer before the itwinui layer. For example, the first few lines in your stylesheet might look like this:

/* defining layer order upfront */
@layer my-reset, itwinui;

/* defining global styles inside the first layer */
@layer my-reset {
  * {
    margin: 0;
    padding: 0;
  }
  ul {
    list-style: none;
  }
}

The itwinui layer name is considered to be a "public" API and is ok to reference in your application code. You may use this knowledge to define a more complex layer order. An important thing to remember is that your layer order must be defined at the very top, before any other layer is even encountered. If your bundler makes it difficult to control the order of CSS imports, then you can manually insert your layer statement into the <head> before any other <style> tags. For example:

<head>
  ...
  <style>@layer reset, itwinui, page, overrides;</style>
  ...
</head>

Note: The code snippet above is only an example to showcase that you can put the itwinui layer anywhere in your overall layer order. The other layer names are not provided by iTwinUI.

As a best practice, you should start with the few layers that are actually needed, rather than creating lots of layers that might become hard to manage. Layer names are by global by default, and it's best to limit global side effects, especially when other teams may be working on the same codebase. Instead of adding too many top-level layers, consider creating nested layers that do not impact the overall layer order.

Version-specific details

Note: "v3", "v2", "v1" refer to @itwin/itwinui-react versions unless otherwise stated.

v3

Starting with @itwin/itwinui-react@3, styles are no longer included automatically. The @itwin/itwinui-react/styles.css file must be imported manually by applications (not by packages, otherwise it could lead to duplicate stylesheets).

This stylesheet is a vendored version of the stylesheets from @itwin/itwinui-variables and @itwin/itwinui-css. All styles are wrapped in the itwinui layer (specifically the nested itwinui.v3 layer). All classes are hashed via CSS modules and therefore considered a private implementation detail. These classes are different from previous major versions to avoid potential conflicts, and can also change at any time depending on the CSS contents. If you need to customize some DOM elements, we recommend passing your own custom className and targeting them in your CSS.

Similar to v2 (see below), the @itwin/itwinui-variables and @itwin/itwinui-css packages are used as development-only dependencies by @itwin/itwinui-react, and should not be installed directly by applications/packages.

v2

As of @itwin/[email protected], all styles are wrapped in the itwinui layer (specifically the itwinui.v2 nested layer). These styles are inlined in javascript and injected at runtime as constructed stylesheets. If you are trying to portal iTwinUI components into a new window/document, you will also need to copy the document.adoptedStyleSheets array along with any other <style>/<link> elements.

Similar to v3, the @itwin/itwinui-variables and @itwin/itwinui-css packages are only used as development dependencies by @itwin/itwinui-react to produce the inline stylesheet contents. These packages should not be installed directly as their stylesheets are not layered by default. While class name changes from @itwin/itwinui-css are not directly relevant for @itwin/itwinui-react users, it is worth paying attention to their respective changelogs in case of any visual changes, DOM structure changes, or CSS variable changes.

iTwinUI v2 shares some classes from v1, so it could lead to some unexpected clashes. To get around this, iTwinUI v2 will revert any styles that it encounters from iTwinUI v1 inside the "v2 boundary". This is done through the use of all: revert-layer. For more details, please read "iTwinUI v1 and v2 coexisting".

Note: The styling strategy was changed drastically in 2.12.0. Prior to that, it was more similar to v1, and while it worked for many cases, we are not documenting the old strategy in detail because it was prone to many issues. Upgrading to 2.12.0 or later is recommended if possible.

v1

As of @itwin/[email protected], all styles are wrapped in the itwinui layer (specifically the itwinui.v1 nested layer). These styles come from the @itwin/[email protected] dependency, and are individually imported inside components. The @itwin/itwinui-variables package is not used.

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