Customize theme

NextUI provides a simple way to customize the default themes, you can change the colors, fonts, breakpoints and everything metioned in the Default Theme documentation.

Customizing theme tokens

To extend or override a token in the default theme, import the createTheme function and add the keys you'd like to override. You can also add new values to the theme.

For example, if you'd like to update the colors in the theme to include your brand colors, here's what you'll do:

// 1. Import `createTheme`
import { createTheme, NextUIProvider, Text } from "@nextui-org/react"

// 2. Call `createTheme` and pass your custom values
const theme = createTheme({
  type: "dark", // it could be "light" or "dark"
  theme: {
    colors: {
      // brand colors
      primaryLight: '$green200',
      primaryLightHover: '$green300',
      primaryLightActive: '$green400',
      primaryLightContrast: '$green600',
      primary: '#4ADE7B',
      primaryBorder: '$green500',
      primaryBorderHover: '$green600',
      primarySolidHover: '$green700',
      primarySolidContrast: '$white',
      primaryShadow: '$green500',

      gradient: 'linear-gradient(112deg, $blue100 -25%, $pink500 -10%, $purple500 80%)',
      link: '#5E1DAD',

      // you can also create your own color
      myColor: '#ff4ecd'

      // ...  more colors
    },
    space: {},
    fonts: {}
  }
})


// 3. Pass the new theme to `NextUIProvider`
<NextUIProvider theme={theme}>
  <App />
</NextUIProvider>

// 4. Now you can use these colors in your components
function MyComponent() {
  return <Text css={{ background: '$myColor' }}>NextUI colors</Text>
}

For further information about createTheme, please refer to the typescript documentation.

Theme type

NextUI provides two themes: light and dark. You can use the type prop to change the base theme.

// 1. Import `createTheme`
import { createTheme, NextUIProvider, Text } from "@nextui-org/react"

// 2. Call `createTheme` and pass your custom values
const myDarkTheme = createTheme({
  type: 'dark',
  theme: {
    colors: {
      // brand colors
      background: '#1d1d1d',
      text: '#fff',
      // you can also create your own color
      myDarkColor: '#ff4ecd'
      // ...  more colors
    },
    space: {},
    fonts: {}
  }
})


// 3. Pass the new theme based on dark type theme to `NextUIProvider`
<NextUIProvider theme={myDarkTheme}>
  <App />
</NextUIProvider>

// 4. Now you can use these colors in your components
function MyComponent() {
  return <Text css={{ color: '$myDarkColor' }}>NextUI with dark theme</Text>
}

useTheme hook

The theme object returned by useTheme hook contains useful token data.

For example, using the theme of the above example (myDarkTheme), you can use any of the theme tokens in your components:

import { useTheme } from '@nextui-org/react';

function MyComponent() {
  const { theme } = useTheme();

  return <p style={{ color: theme.colors.myDarkColor.value }}>NextUI</p>;
}

You can use the returned theme objects to read the tokens, like so:

// default theme
theme.colors.background; // var(--nextui-colors-background)
theme.colors.background.value; // #ffffff
theme.colors.background.token; // background
theme.colors.background.scale; // colors
theme.colors.background.variable; // --nextui-colors-background
theme.colors.background.computedValue; // var(--nextui-colors-background)

// (myDarkTheme) theme
dark.colors.background; // var(--nextui-colors-background)
dark.colors.background.value; // #1d1d1d
dark.colors.background.token; // background
dark.colors.background.scale; // colors
dark.colors.background.variable; // --nextui-colors-background
dark.colors.background.computedValue; // var(--nextui-colors-background)

For more information about the theme tokens, see the Stitches Custom theming documentation.

Theme specific styles

You can add styles based on themes by retrieving the generated theme class.

import { Button, createTheme, styled } from '@nextui-org/react';

const myTheme = createTheme({
  theme: {
    colors: {...},
    fonts: {...},
    space: {...},
    // ...
  }
});

const MyButton = styled(Button, {
  borderRadius: '9999px',
  fontSize: '15px',
  border: '0',

  [`.${myTheme} &`]: {
    backgroundColor: '$blue700',
  },
});

function MyComponent() {
  return (
    <div className={myTheme}>
      <MyButton>Button</MyButton>
    </div>
  )
};

Global styles

If you need to implement styles globally or handling things like global resets, you can use the globalCss function.

import { globalCss } from '@nextui-org/react';

const globalStyles = globalCss({
  body: { margin: 0 }
});

const MyApp = () => {
  globalStyles();
  return <div />;
};

Keyframes

A function to create a global CSS @keyframe rule.

import { keyframes, Text, styled } from '@nextui-org/react';

const scaleUp = keyframes({
  '0%': { transform: 'scale(1)' },
  '100%': { transform: 'scale(1.5)' }
});

const StyledText = styled(Text, {
  '&:hover': {
    animation: `${scaleUp} 200ms`
  }
});