@nexusui/theme v4.0.0

NexusUI MUI Theme

This is a simple MUI theme drop in for your React application, which aims to be the source of truth for the NexusUI Design system.

Installation

# With yarn:
yarn add @nexusui/theme

# With npm:
npm install --save @nexusui/theme

Peer Dependencies

Our theme also expects that you have the following dependencies installed in your project. You can install them quickly if you haven't already:

# With yarn:
yarn add @mui/material @emotion/react @emotion/styled @mui/x-data-grid @mui/x-date-pickers @mui/x-tree-view

# With npm:
npm install --save @mui/material @emotion/react @emotion/styled @mui/x-data-grid @mui/x-date-pickers @mui/x-tree-view

Usage

Basic theme & Fonts Import

In your main React application entrypoint, wrap your whole app with the ThemeProvider and pass in the NexusUI theme to the theme prop. You should also include the CssBaseline component from MUI — this component includes a CSS reset to standardize default styles across browsers for a more consistent experience. Additionally, you should import the fonts file, which provides a self-hosted version of the Open Sans font through Fontsource.

NOTE: The fonts file from the NexusUI theme includes the 400 (regular), 600 (semi-bold), 700 (bold), and 800 (extra-bold) weights. If you need 300 (light) or 500 (medium) for your application, you can include them separately (see below).

import CssBaseline from '@mui/material/CssBaseline';
import theme from '@nexusui/theme';
import '@nexusui/theme/fonts';
// include these only if you need Open Sans light or medium weight in your application
// import '@fontsource/open-sans/300.css;
// import '@fontsource/open-sans/500.css;
...

<ThemeProvider theme={theme}>
  <CssBaseline />
  {/* Your Application Contents Here */}
</ThemeProvider>

Supporting Light & Dark Theme

If you want to support both light and dark themes in your application, you can dynamically switch which theme you pass into the ThemeProvider.

import CssBaseline from '@mui/material/CssBaseline';
import lightTheme, { LanguageType, useThemeWithLocale, darkTheme } from "@nexusui/theme";
import '@nexusui/theme/fonts';

const themeMode = localStorage.getItem("theme") || 'light'; // Or read from redux
const theme = themeMode === 'dark' ? darkTheme : lightTheme;

<ThemeProvider theme={theme}>
  <CssBaseline />
  {/* Your Application Contents Here */}
</ThemeProvider>

Supporting localization

If you also want to support both MUI and Nexus UI components localization switching in your app, you can use useThemeWithLocale to simplify this step.(see below).

import CssBaseline from '@mui/material/CssBaseline';
import lightTheme, { LanguageType, useThemeWithLocale, darkTheme } from "@nexusui/theme";
import '@nexusui/theme/fonts';

// Or read theme mode from redux
const themeMode = localStorage.getItem("theme") || 'light';
const theme = themeMode === 'dark' ? darkTheme : lightTheme;

// Or read language from redux
const language = localStorage.getItem("language")  || 'en-US'; // Or read from redux

const themeWithLocale = useThemeWithLocale(language as LanguageType, theme);

<ThemeProvider theme={themeWithLocale}>
  <CssBaseline />
  {/* Your Application Contents Here */}
</ThemeProvider>

Migration Guide

3.X.X => 4.0.0

Version 4.0.0 of @nexusui/theme includes a single breaking change with dependencies. When upgrading, you'll need to add the following dependencies:

• @mui/x-tree-view

You can also remove your @mui/lab dependency if you were only using it for the TreeView component, which was migrated out of the lab.

2.X.X -> 3.0.0

Version 3.0.0 of @nexusui/theme includes a single breaking change with dependencies. When upgrading, you'll need to update your dependencies to the following minimum versions:

• @mui/x-data-grid to version 6.5.0 or greater.
• @mui/x-date-pickers to version 6.7.0 or greater.

1.X.X -> 2.0.0

Version 2.0.0 of @nexusui/theme includes a few minor breaking changes to improve consistency and compatibility and also introduces our new dark theme. When upgrading from version 1.x, take note of the following breaking changes.

1) Open Sans fonts no longer automatically included

We previously bundled the Open Sans font dependencies along with our theme automatically to simplify the integration for users. However, including these CSS files automatically in our NPM package caused the theme to no longer be compatible with NextJS applications. We have removed this automatic import in version 2.0.0, so when upgrading, you will need to manually add the following import to your top-level index file:

import '@nexusui/theme/fonts';

2) onDark palette renamed to alternate

We previously had a supplemental palette called 'onDark' (theme.palette.onDark) which was used sparingly for components that were rendered on a dark blue background. We've renamed this palette to be more general in order to make sense for the dark theme. You should be able to use a simple find & replace strategy to replace all instances of onDark with alternate throughout your application.

3) background.blue palette renamed to background.alternate

Similar to the onDark palette, we have renamed the 'background.blue' palette (theme.palette.background.blue) to 'background.alternate' for compatibility with the dark theme (the alternate background is not a shade of blue in the dark theme). This is another case where you can use a find & replace strategy to update the name throughout your application.

0.X.X -> 1.0.0

Version 1.0.0 of @nexusui/theme is a major refactor to better align with Material Design styles and the Material UI theming mechanism. This update also improves alignment with the Nexus design assets currently accessible through Figma.

In general, we recommend trying to reduce your custom style/theme overrides that you may have in place for MUI elements in your application (you can gradually add them back in if they are, in fact, necessary). We've put a lot of effort into making these components look correct for NexusUI applications out-of-the-box with little to no styling required. Any overrides that you currently have in place will likely interfere and prevent you from reaping the full benefits of the updated theme.

When updating to this version, there are some key changes that you will need to be aware of to make the process as smooth as possible.

1) New Peer Dependencies

We converted the theme package to TypeScript. To add custom theming for MUI-X components, we needed to add new dependencies on their type definitions. You will need to install these packages to avoid type errors when using the theme.

# With yarn:
yarn add @mui/x-data-grid @mui/x-date-pickers

# With npm:
npm install --save @mui/x-data-grid @mui/x-date-pickers

2) Color Palette Imports

Individual color palettes are no longer available from a nested colors folder. Instead, import them from the package root:

// before
import { black, blue, green, grey, orange, red } from '@nexusui/theme/colors';

// after
import { black, blue, green, grey, orange, red } from '@nexusui/theme';

3) Updated Color Palette Shades

• Individual color palettes have been updated for compatibility with the MUI theme mechanism. These now include shades for 50, 100, 200, 300, 400, 500, 600, 700, 800, 900. Note that the 0 and 1000 shades have been removed.
• All palettes previously included pure white as their lightest shade and pure black as their darkest shade. The lightest/darkest shade in each palette is now a version of the base color. If you need pure white/black, you can access them from the common palette or using the hex code.

// before
import { blue } from '@nexusui/theme/colors';
const myWhite = blue[50];
const myBlack = blue[1000];

// after
import { blue } from '@nexusui/theme';
const myDarkColor = blue[900];
const myLightColor = blue[50];
const myWhite = theme.palette.common.white; // or '#fff'
const myBlack = theme.palette.common.black; // or '#000'

• Some palettes previously did not have all shades defined, so some shades (e.g., 500 and 700) might have been exactly the same. Every variant in each palette is now a unique shade that evenly progresses from light to dark (this is most notable in the range > 500 — there is a wider variety of darker shades now for most colors).

• The blue palette was also overhauled (it's actually a combination of the previous blue and secondary blue palettes — we now have blue and darkBlue). Because the base color shifted, there is no direct 1-1 mapping of old shades to new shades, but a reasonable mapping would be:

oldBlue[0] -> theme.palette.common.white
oldBlue[50] -> grey[200]
oldBlue[100] -> blue[50]
oldBlue[200] -> blue[100]
oldBlue[300] -> blue[200]
oldBlue[400] -> blue[600]
oldBlue[500] -> blue[700]
oldBlue[600] -> darkBlue[700]
oldBlue[700] -> darkBlue[700]
oldBlue[800] -> darkBlue[800]
oldBlue[900] -> darkBlue[900]
oldBlue[1000] -> theme.palette.common.black

4) Removed Tertiary and Dark Palettes

We previously extended the default MUI theme structure to include tertiary and dark palettes. Additionally, the primary and secondary palettes were both based on the same blue palette.

To better align with how MUI theming works, we have removed the tertiary palette and moved those definitions to secondary to provide a better accent color (instead of blue and blue).

// before
const myBlueColor = theme.palette.secondary;
const myGreenColor = theme.palette.tertiary;

// after
const myBlueColor = theme.palette.primary;
const myGreenColor = theme.palette.secondary;

The dark palette was previously used to handle variations of components that were displayed on a dark colored background. The spirit of this palette has been maintained, but renamed to alternate. This palette is not meant to be used like the other palettes (it does have all shades defined, but they are all pure white) — it's exclusively for use with the MUI components that support a 'white' version for use on dark backgrounds (Button, IconButton, CheckBox, Fab, Radio, Slider, Switch, ToggleButtonGroup, ToggleButton, Chip) by passing it to the color prop.

// before
<Button color={'dark'}/>

// after
<Button color={'alternate'}/>

5) Updated Typography Variants

The Typography variants have been slightly modified and updated to define the styles for previously undefined defaults from MUI. Notable changes include:

• added a display variant — this is the biggest and boldest style we offer
• added a definition for h6, subtitle, and subtitle2
• custom 'body' styles have been shifted down (subtitle styles take the place of the larger sizes):
  • bodyXL has been removed -> bodyL
  • bodyL -> body
  • body -> bodyS
• removed additional custom variants in favor of default MUI variants:
  • label -> bodyS
  • strong -> <Typography fontWeight={700}>
  • footer -> caption
  • user -> <Typography variant={'bodyS'} fontWeight={700}>

6) Default Roundness (Border Radius)

The theme default roundness property in the theme (affects the roundness of corners on various MUI elements) has been changed from 8px to 0.25rem (4px). If you were basing some of your custom styles on the theme roundness, you may need to multiply your values by 2 to maintain the same style as before.