Develop with StrataKit

Learn how to set up StrataKit in your React project.

Quick start

This guide is for application developers. If you’re building a package on top of StrataKit, you can usually skip most of these steps, since the host application will already have StrataKit set up for you.

Open the minimal starter template on StackBlitz to see a working example and to understand the steps listed below.

Install the StrataKit packages
Terminal window
```
npm add @stratakit/mui @stratakit/icons
```
You will also need to install @mui/material and its peer dependencies (@emotion/styled and @emotion/react).
Configure your bundler

StrataKit icons should be served as external SVG files, so your bundler needs to be configured to not inline them. See Bundler configuration below.
Set up TypeScript types

StrataKit augments some MUI component types. Add @stratakit/mui/types.d.ts to the existing types field in your tsconfig file:
tsconfig.json
```
{
  "compilerOptions": {
    "types": ["@stratakit/mui/types.d.ts"]
  }
}
```
If your tsconfig file does not already have a types field, you can alternatively add @stratakit/mui/types.d.ts using a triple-slash directive in any declaration file.
Set up the Root component

Wrap your app’s entrypoint with the <Root> component from @stratakit/mui:
src/App.tsx
```
import { Root } from "@stratakit/mui";

export function App() {
  return <Root colorScheme="light">{/* Your app goes here */}</Root>;
}
```
That’s it! You can now use any component from @mui/material, and it will automatically be styled with StrataKit’s visual language.

Don’t use MUI’s ThemeProvider, StyledEngineProvider, or CssBaseline directly. The Root component handles all of that for you.
Use icons (optional)

To use StrataKit icons, import the .svg files from @stratakit/icons and pass them to the <Icon> component from @stratakit/mui:
```
import { Icon } from "@stratakit/mui";
import svgSettings from "@stratakit/icons/settings.svg";

<Icon href={svgSettings} />;
```
Do not use any icons from @mui/icons-material as they are not compatible with StrataKit.

Bundler configuration

You will need to ensure that your bundler does not inline .svg files, so that StrataKit icons can be used as external HTTP resources.

Configure build.assetsInlineLimit.

export default defineConfig({
  build: {
    assetsInlineLimit: (filePath) => !filePath.endsWith(".svg"),
  },
});

Configure output.dataUriLimit.

export default {
  output: {
    dataUriLimit: { svg: 0 },
  },
};

Enable the file loader for .svg files.

esbuild.build({
  loader: { ".svg": "file" },
});

Self-hosting the fonts

StrataKit uses InterVariable as its interface font. While a CDN fallback is provided automatically, we recommend self-hosting for better performance and reliability.

To self-host InterVariable, download the InterVariable.woff2 and InterVariable-Italic.woff2 font files from the official website, and serve them alongside your other assets. Then include the following CSS in the <head> of your document, replacing the placeholder paths with the correct path to where the fonts are located:

<style>
  @font-face {
    font-family: InterVariable;
    font-style: normal;
    font-weight: 100 900;
    font-display: swap;
    src: url("/path/to/InterVariable.woff2") format("woff2");
  }

  @font-face {
    font-family: InterVariable;
    font-style: italic;
    font-weight: 100 900;
    font-display: swap;
    src: url("/path/to/InterVariable-Italic.woff2") format("woff2");
  }
</style>

Build tools such as Vite can handle url() references and automatically copy these files into your output directory with hashed file names. These files can then be safely served with HTTP caching without blocking upgrades to newer versions of the fonts.

Migrating from iTwinUI

If you’re using StrataKit alongside the current stable version of iTwinUI, you’ll need to set up the theme bridge to ensure both libraries work together seamlessly.

Migrating from legacy StrataKit

If you’re using legacy StrataKit components (from before @stratakit/mui was introduced), see Migrating from legacy StrataKit.