Default Theme

NextUI default theme is based on Stitches Theme Tokens

Colors

NextUI includes a default color palette out-of-the-box that is a great starting point if you don't have your own specific branding in mind.

You can access the colors through the theme object or using tokens whitin the css prop or styled components, see the theme object for more information.

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

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

  return (
    <div>
      <Text
        css={{
          color: '$blue800',
          fontSize: '$sm',
          padding: '$2 $4'
        }}
      >
        Using tokens
      </Text>
      <p
        style={{
          color: theme.colors.primary.value,
          fontSize: theme.fontSizes.sm.value,
          padding: `${theme.space[2].value} ${theme.space[4].value}`
        }}
      >
        Using color theme value
      </p>
    </div>
  );
};

By default these colors can be used by the color, borderColor, backgroundColor, fill, and so on, here is the complete list of properties where you can use the color tokens Stitches Property Mapping.

export default {
  colors: {
    // generic colors
    white: '#ffffff',
    black: '#000000',
    //semantic colors (light)
    blue50: '#EDF5FF',
    // ...
    blue900: '#00254D',
    // ...

    // brand colors
    primaryLight: '$blue200',
    primaryLightHover: '$blue300', // commonly used on hover state
    primaryLightActive: '$blue400', // commonly used on pressed state
    primaryLightContrast: '$blue600', // commonly used for text inside the component
    primary: '$blue600',
    primaryBorder: '$blue500',
    primaryBorderHover: '$blue600',
    primarySolidHover: '$blue700',
    primarySolidContrast: '$white', // commonly used for text inside the component
    primaryShadow: '$blue500'

    // ... rest of colors (secondary, success, warning, error, etc)
  }
};

Brand

Understanding the Base scale

There are 10 steps in each scale from 50 to 900. Each step was designed for at least one specific use case.

This table is a simple overview of the most common use case for each step. However, there are many exceptions and caveats to factor in, which are covered in further detail below.

StepUse Case
50UI element background
100Hovered UI element background
200Active / Selected UI element background
300Subtle borders and separators
400UI element border and focus rings
500Hovered UI element border
600Solid backgrounds
700Hovered solid backgrounds
800Low-contrast text
900High-contrast text

Note: NextUI uses different colors for each theme type (light, dark). You can check it out by toggling the docs theme on the navbar.

Base

We recommend adding a palette that ranges from 100 to 900. You can use tools like Eva Design System or RadixUI Colors to generate a palette.

Accents

Layout

Highlights

Typography

To manage Typography options you can use the following keys:

  • fonts (font families)
  • fontSizes
  • fontWeights
  • lineHeights
  • letterSpacings

1. Fonts

export default {
  // default theme object
  colors: {...}, // color palette object
  fonts: {
    sans: "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto',
    'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;",
    mono: "Menlo, Monaco, 'Lucida Console', 'Liberation Mono',
    'DejaVu Sans Mono', 'Bitstream Vera Sans Mono'"
  }
  ...
};

2. Font sizes

export default {
  // default theme object
  colors: {...}, // color palette object
  fonts: {...}, // font families object
  fontSizes: {
    xs: '0.75rem', /* 12px */
    sm: '0.875rem', /* 14px */
    base: '1rem', /* 16px */
    md: '1rem', /* 16px */
    lg: '1.125rem', /* 18px */
    xl: '1.25rem', /* 20px */
    xl2: '1.5rem', /* 24px */
    xl3: '1.875rem', /* 30px */
    xl4: '2.25rem', /* 36px */
    xl5: '3rem', /* 48px */
    xl6: '3.75rem', /* 60px */
    xl7: '4.5rem', /* 72px */
    xl8: '6rem', /* 96px */
    xl9: '8rem', /* 128px */
  }
  ...
};

3. Font weights

export default {
  // default theme object
  colors: {...}, // color palette object
  fonts: {...}, // font families object
  fontSizes: {...}, // font sizes object
  fontWeights: {
    hairline: 100,
    thin: 200,
    light: 300,
    normal: 400,
    medium: 500,
    semibold: 600,
    bold: 700,
    extrabold: 800,
    black: 900
  }
  ...
};

4. Line heights

export default {
  // default theme object
  colors: {...}, // color palette object
  fonts: {...}, // font families object
  fontSizes: {...}, // font sizes object
  fontWeights: {...}, // font weights object
  lineHeights: {
    xs: 1, /* 16px */
    sm: 1.25, /* 20px */
    base: 1.5, /* 24px */
    md: 1.5, /* 24px */
    lg: 1.75, /* 28px */
    xl: 1.75, /* 28px */
    xl2: 2, /* 32px */
    xl3: 2.25, /* 36px */
    xl4: 2.5, /* 40px */
    xl5: 1,
    xl6: 1,
    xl7: 1,
    xl8: 1,
    xl9: 1
  }
  ...
};

4. Letter Spacings

export default {
  // default theme object
  colors: {...}, // color palette object
  fonts: {...}, // font families object
  fontSizes: {...}, // font sizes object
  fontWeights: {...}, // font weights object
  lineHeights: {...}, // line heights object
  letterSpacings: {
    tighter: '-0.05em',
    tight: '-0.025em',
    normal: '0',
    wide: '0.025em',
    wider: '0.05em',
    widest: '0.1em'
  }
  ...
};

Radius

NextUI provides a set of commons sizes for controlling the border-radius of an element.

export default {
  // default theme object
  colors: {...}, // color palette object
  fonts: {...}, // font families object
  fontSizes: {...}, // font sizes object
  fontWeights: {...}, // font weights object
  lineHeights: {...}, // line heights object
  radii: {
    xs: '7px',
    sm: '9px',
    md: '12px',
    base: '14px',
    lg: '14px', // preferred value by NextUI components
    xl: '18px',
    squared: '33%',
    rounded: '50%',
    pill: '9999px'
  }
  ...
};

Border weights

NextUI includes by default a set of common border weights.

export default {
  // default theme object
  colors: {...}, // color palette object
  fonts: {...}, // font families object
  fontSizes: {...}, // font sizes object
  fontWeights: {...}, // font weights object
  lineHeights: {...}, // line heights object
  radii: {...}, // border radius object
  borderWeights: {
    light: '1px',
    normal: '2px',
    bold: '3px',
    extrabold: '4px',
    black: '5px'
  }
  ...

Spacing

NextUI has a set of most common spaces values which allows you to customize the global spacing and sizing scale for your project. By default these spacing value can be referenced by the padding, margin, and top, left, right, bottom, width, height and more styles.

You can see the complete space list on Stitches Property Mapping

export default {
  // default theme object
  // ... previous theme properties
  spacing: {
    0: '0rem',
    xs: '0.5rem',
    sm: '0.75rem',
    md: '1rem',
    lg: '1.375rem',
    xl: '2.25rem',
    px: '1px',
    1: '0.125rem',
    2: '0.25rem',
    3: '0.375rem',
    4: '0.5rem',
    5: '0.625rem',
    6: '0.75rem',
    7: '0.875rem',
    8: '1rem',
    9: '1.25rem',
    10: '1.5rem',
    11: '1.75rem',
    12: '2rem',
    13: '2.25rem',
    14: '2.5rem',
    15: '2.75rem',
    16: '3rem',
    17: '3.5rem',
    18: '4rem',
    20: '5rem',
    24: '6rem',
    28: '7rem',
    32: '8rem',
    36: '9rem',
    40: '10rem',
    44: '11rem',
    48: '12rem',
    52: '13rem',
    56: '14rem',
    60: '15rem',
    64: '16rem',
    72: '18rem',
    80: '20rem',
    96: '24rem'
  }
  ...
};
NameSpacePixels
00rem0px
px1px1px
10.125rem2px
20.25rem4px
30.375rem6px
4 (xs)0.5rem8px
50.625rem10px
6 (sm)0.75rem12px
70.875rem14px
8 (md)1rem16px
9 (lg)1.25rem20px
101.5rem24px
111.75rem28px
122rem32px
13 (xl)2.25rem36px
142.5rem40px
152.75rem44px
163rem48px
173.75rem60px
184rem64px
205rem80px
246rem96px
287rem112px
328rem128px
369rem144px
4010rem160px
4411rem176px
4812rem192px
5213rem208px
5614rem224px
6015rem240px
6416rem256px
7218rem288px
8020rem320px
9624rem384px

Breakpoints

NextUI exposes to you a predefined set of commonly used breakpoints which are used on components like Container and Grid.

export default {
  // default theme object
  // ... previous theme properties
  breakpoints: {
    xs: '650px',
    sm: '960px',
    md: '1280px',
    lg: '1400px',
    xl: '1920px'
  }
  ...
};

z-index values

NextUI provides a minimal set of z-Indices out of the box to help control the stacking order of components.

export default {
  // default theme object
  // ... previous theme properties
  zIndices: {
    1: '100',
    2: '200',
    3: '300',
    4: '400',
    5: '500',
    10: '1000',
    max: '9999'
  }
  ...
};

Shadows

NextUI provides a curated set of predefined shadows for light and dark themes.

// light theme
export const lightTheme = {
  // default theme object
  // ... previous theme properties
  shadows: {
    xs: '0 2px 8px 1px rgb(104 112 118 / 0.07), 0 1px 1px -1px rgb(104 112 118 / 0.04)',
    sm: '0 2px 8px 2px rgb(104 112 118 / 0.07), 0 2px 4px -1px rgb(104 112 118 / 0.04)',
    md: '0 12px 20px 6px rgb(104 112 118 / 0.08)',
    lg: '0 12px 34px 6px rgb(104 112 118 / 0.18)',
    xl: '0 25px 65px 0px rgb(104 112 118 / 0.35)'
  },
   // to use along with css dropShadow utility
  dropShadows: {
    xs: 'drop-shadow(0 2px 4px rgb(104 112 118 / 0.07)) drop-shadow(0 1px 1px rgb(104 112 118 / 0.04))',
    sm: 'drop-shadow(0 2px 8px rgb(104 112 118 / 0.07)) drop-shadow(0 2px 4px rgb(104 112 118 / 0.04))',
    md: 'drop-shadow(0 4px 12px rgb(104 112 118 / 0.08)) drop-shadow(0 20px 8px rgb(104 112 118 / 0.04))',
    lg: 'drop-shadow(0 12px 24px rgb(104 112 118 / 0.15)) drop-shadow(0 12px 14px rgb(104 112 118 / 0.1))',
    xl: 'drop-shadow(0 25px 34px rgb(104 112 118 / 0.35))'
  }
  ...
};
// dark theme
export const darkTheme = {
  // default theme object
  // ... previous theme properties
  shadows: {
    xs: '0 2px 8px 1px rgb(0 0 0 / 0.07), 0 1px 1px -1px rgb(0 0 0 / 0.04)',
    sm: '0 2px 8px 2px rgb(0 0 0 / 0.07), 0 2px 4px -1px rgb(0 0 0 / 0.04)',
    md: '0 12px 20px 6px rgb(0 0 0 / 0.08)',
    lg: '0 12px 34px 6px rgb(0 0 0 / 0.18)',
    xl: '0 25px 65px 0px rgb(0 0 0 / 0.35)'
  },
   // to use along with css dropShadow utility
  dropShadows: {
    xs: 'drop-shadow(0 2px 4px rgb(0 0 0 / 0.07)) drop-shadow(0 1px 1px rgb(0 0 0 / 0.04))',
    sm: 'drop-shadow(0 2px 8px rgb(0 0 0 / 0.07)) drop-shadow(0 2px 4px rgb(0 0 0 / 0.04))',
    md: 'drop-shadow(0 4px 12px rgb(0 0 0 / 0.08)) drop-shadow(0 20px 8px rgb(0 0 0 / 0.04))',
    lg: 'drop-shadow(0 12px 24px rgb(0 0 0 / 0.15)) drop-shadow(0 12px 14px rgb(0 0 0 / 0.1))',
    xl: 'drop-shadow(0 25px 34px rgb(0 0 0 / 0.35))'
  }
  ...
};
gradient blue backgroundgradient violet background