Skip to content

InseeFrLab/onyxia-ui

Repository files navigation

The Onyxia UI toolkit


Documentation

This project is a React UI toolkit that implement a design system created for Onyxia by Marc Hufschmitt.

This project provide some custom components but you can also use any MUI component they will be automatically styled to fit the design system.

  • Optimized for typescript, theme customization without module augmentation.
  • Built in support for the dark mode.
  • If you want to diverge from the Onyxia Design system, the theme is customizable, you can for example change the fonts and the colors.
  • Provide splash screen that hide the screen when needed.
  • Perfect for building white label Web APP: The theme and assets, icons can be configured at runtime.

Disclaimer: onyxia-ui is specifically designed to build SPA (Vite projects) and is not SSR compatible (Not compatible with Next).

Note

There's an extention of Onyxia UI for creating Landing pages: gitlanding

Showcase

Installation

yarn add onyxia-ui @mui/[email protected] @emotion/react @emotion/styled tss-react

Usage

The easyer way to get started is to checkout this demo repository: onyxia-ui + gilanding starter.

You can see more advanced examples here: test app of this repo.

Icons

Onyxia-ui enables you to use icons from the Material Design Library.
Or to provide your own icon as SVG urls.

Using Material Icons: With hard import

If you know what icon you'll need ahead of time, implement this approach:

yarn add @mui/[email protected]

Now if you want to use AccessAlarms

import AccessAlarmIcon from "@mui/icons-material/AccessAlarm";

<Icon icon={AccessAlarmIcon} />;

Using Material Icons: With lazy loading

If you don't know ahead of time what icon you will need. This is the case if your app renders user generated content that might include icons then you can opt for downloading the icons dynamically.
Be aware that this involves including a 35MB directory of icons in your public/ directory which will end up impacting your docker image size.

"scripts": {
    "prepare": "copy-material-icons-to-public"
}

OPTIONAL: Use cache in your Workflow to speed up your CI pipeline

    - uses: bahmutov/npm-install@v1
      env:
        XDG_CACHE_HOME: "/home/runner/.cache/yarn"

This will enable you to do this:

import { Icon } from "onyxia-ui/Icon";

// https://mui.com/material-ui/material-icons/?selected=AccessAlarms
<Icon icon="AccessAlarms" />;

Or, if you want type safety:

import { Icon } from "onyxia-ui/Icon";
import { id } from "tsafe/id";
import type { MuiIconComponentName } from "onyxia-ui/MuiIconComponentName";

// https://mui.com/material-ui/material-icons/?selected=AccessAlarms
<Icon icon={id<MuiIconComponentName>("AccessAlarms")} />;

Using custom SVGs as icons

import myIconSvgUrl from "./assets/my-icon.svg";

<Icon icon={myIconSvgUrl} />
<Icon icon="https://example.com/foo/my-icon.svg" />