Scientific React UI

Scientific React UI components, based on MUI. SciReactUI is the React implementation of the Diamond Design System, a theme and component library to make websites at scientific institutions simple to create. Our StoryBook website has indepth information about the library and each component, but this Readme is a good place to start.

If you would like to contribute, please see our Contributing document.

Using

Installing

Install as usual.

"One of:"
- pnpm add @diamondlightsource/sci-react-ui
- npm i @diamondlightsource/sci-react-ui
- yarn add @diamondlightsource/sci-react-ui

Import the library's font styles once, e.g. in your app's entry point:

import "@diamondlightsource/sci-react-ui/font-styles.css";

@mui/icons-material and react-icons are peer dependencies, so install them too if you use icon-based components:

"One of:"
- pnpm add @mui/icons-material react-icons
- npm i @mui/icons-material react-icons
- yarn add @mui/icons-material react-icons

For icons in your own application code (not required by sci-react-ui itself), we recommend Lucide - see the Icons foundation page in Storybook for guidance:

"One of:"
- pnpm add lucide-react
- npm i lucide-react
- yarn add lucide-react

Usage

First use the ThemeProvider and wrap your App.

import { ThemeProvider } from "@diamondlightsource/sci-react-ui";

root.render(
  <ThemeProvider>
    <App />
  </ThemeProvider>,
);

Use the provided DiamondDSTheme with the ThemeProvider, or create your own. The theme controls colour via semantic surface tokens and consists of two parts:

• Theme configuration (DiamondDSTheme.ts)
• Semantic role tokens (diamond-ds-roles.css)

Navigation components support either static links (with href) or the use of a routing library (with linkComponent and to). For NavLink and FooterLink, if both linkComponent and to are provided, it will use linkComponent. If not, it falls back to using href.

An example with static links

<Navbar>
  <NavLinks>
    <NavLink href="/about">About</NavLink>
  </NavLinks>
</Navbar>

and an example using react-router:

import { NavLink } from "react-router-dom";

<Navbar linkComponent={NavLink}>
  <NavLinks>
    <NavLink linkComponent={NavLink} to="/about">
      About
    </NavLink>
  </NavLinks>
</Navbar>

For Breadcrumbs, to use static links, omit the linkComponent prop and Breadcrumbs will use a Link component with standard href attributes.

import { Breadcrumbs } from "@diamondlightsource/sci-react-ui";

function App() {
  return <Breadcrumbs path={window.location.pathname} />;
}
export default App;

To use the Breadcrumbs component with your routing library, use a route provider from your preferred library. For example, to use react-router's BrowserRouter, install react-router-dom:

npm i react-router-dom

Next, use the BrowserRouter which can be used at the top level:

import { BrowserRouter } from "react-router-dom";
import { ThemeProvider } from "@diamondlightsource/sci-react-ui";

root.render(
	<ThemeProvider>
		<BrowserRouter>
			<App />
		</BrowserRouter>
	</ThemeProvider>
)

Then pass your library's corresponding Link component to Breadcrumbs in the linkComponent prop, for example:

import { NavLink } from "react-router-dom";
import { Breadcrumbs } from "@diamondlightsource/sci-react-ui";

function App() {
  return <Breadcrumbs path={window.location.pathname} linkComponent={NavLink} />;
}
export default App;

The Navbar component supports multiple slot props for flexible layout customization: leftSlot, centreSlot, rightSlot. If a logo is defined (either via the logo prop or from the theme), the layout will arrange elements in the following order from left to right: logo, leftSlot, rightSlot. The centreSlot is absolutely positioned at 50% horizontally, which means it stays centered regardless of the content on the left or right. However, if the content in the left or right slots is too wide, it may overlap with the centre slot.

Any children passed to the Navbar (NavLinks in the following example) will be placed in a horizontal Stack after the leftSlot.

To control the width of the Navbar contents, containerWidth can be passed which sets the maxWidth property of a Container. This can be set to false to not constrain the contents or to a Breakpoint e.g. 'sm' where 'lg' is the default.

import { Container, Typography } from "@mui/material";
import { Navbar, NavLink, NavLinks } from "@diamondlightsource/sci-react-ui";

function App() {
  return (
    <>
      <Navbar
        leftSlot={<Typography>left</Typography>}
        centreSlot={<Typography>centre</Typography>}
        rightSlot={<Typography>right</Typography>}
        containerWidth={false}
      >
        <NavLinks key="links">
          <NavLink href="#" key="first">
            A link
          </NavLink>
        </NavLinks>
      </Navbar>
    </>
  );
}
export default App;

The Footer component supports multiple slot props, the same as Navbar (leftSlot, centreSlot, rightSlot).

If a logo is defined (either via the logo prop or from the theme), the layout will arrange elements in the following order from left to right: leftSlot, rightSlot, logo. The centreSlot is absolutely positioned at 50% horizontally, which means it stays centered regardless of the content on the left or right. However, if the content in the left or right slots is too wide, it may overlap with the centre slot.

Any children passed to the Footer will be placed in a horizontal Stack after the leftSlot.

See Storybook for guidance on adapting the Diamond DS theme to your own palette, using Material React Table with the theme, and avoiding dark mode flicker in SSR/client-side apps.

Documentation

Documentation is created with Storybook. Additional information about auth, colours and theming can be found there.

Read and play with it at diamondlightsource.github.io/sci-react-ui

Developing

Code can be found at github.com/DiamondLightSource/sci-react-ui.

You'll need pnpm installed to build it. (note: it is automatically installed as a feature if you are using devcontainers) See tools.md for list of other tools used in this library

Build

First install all packages

pnpm install

Build with rollup

pnpm run rollup

Storybook

To view the components in Storybook use:

pnpm run storybook

Unit Test

Test with Jest

pnpm run test

App test

Create a test app.

To test the package, you may be able to link the package directly from source:

pnpm link <path-to-this-app-folder>

But if that doesn't work, you can try pack, then install:

In the package repo:

pnpm pack

In the test app repo:

pnpm install <path-to-this-app-folder>/diamondlightsource-sci-react-ui-0.0.1.tgz

Dev app

Test out components in the dev app.

First install dependencies with:

pnpm dev:install

Then run the dev app:

pnpm dev

You can modify dev/src/App.tsx to test out the theme and components

Publishing

Always publish a release candidate ("vx.y.z-rc.n") and leave at least 72 hours for testing before a normal release. Steps needed when publishing a new version.

• Create a new branch
  • Update the version in ./package.json (greater than the published one!)
  • Update the changelog in ./changelog.md with added/changed/fixed, new version number and today's date.
  • Check this readme still makes sense with the new changes you are about to publish.
  • Check the introduction file ./src/storybook/Introduction.mdx in Storybook still makes sense.
• Push the branch, get it reviewed and merge.
• Now create a new tag in the format "v" followed by the version (e.g. "v1.2.3", or "v1.2.3-rc.1")
  • Push it.
• A new npm version should now have been published:
  • https://www.npmjs.com/package/@diamondlightsource/sci-react-ui?activeTab=versions

GitHub release

• GitHub releases and create a new draft release https://github.com/DiamondLightSource/sci-react-ui/releases
  • Select the new tag in the "Choose a tag" drop down.
  • Copy in the npm url "See https://www.npmjs.com/package/@diamondlightsource/sci-react-ui"
  • Copy in the top section of the changelog.
  • Press "Publish Release"
• It is now published!

Post Publish Changes

It's useful to increase the version in ./package.json and add "rc", e.g "version": "0.2.1rc",. and create a new section in ./changelog.md so subsequent changes can be append when needed/ e.g.:

[v#.#.#] - 2025-##-##
---------------------

### Added
-

### Fixed
-

### Changed
-