onyxia-ui

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.
• Icons are downloaded at runtime. The full catalog of mui icons is is available at runtime. (No hard import required)

Disclaimer: onyxia-ui is specifically designed to build SPA and is not SSR compatible.

A note about the integration of Onyxia and Onyxia-UI can be found here.

Showcase

datalab.sspcloud.fr

datalab.sspcloud.fr with "France" palette

datalab.sspcloud.fr with "Ultraviolet" palette

www.sspcloud.fr

Quick start

yarn add onyxia-ui @mui/material @emotion/react @emotion/styled

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/icons-material

src/theme.ts

const { ThemeProvider } = createThemeProvider({
    // ...
    publicUrl: undefined,
});

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

Documentation

The documentation is under the form of a very simple demo project.
The actual theme configuration happens here.
If you want to experiment with it you can run the demo app with:

NOTE for Storybook users: As of writing this lines storybook still uses by default emotion 10.
mui and TSS runs emotion 11 so there is some changes to be made to your .storybook/main.js to make it uses emotion 11.

Launch dev environment

git clone https://github.com/garronej/onyxia-ui
cd onyxia-ui
yarn
yarn build
yarn start