Layout

NextUI's plugin provides a variety of layout customization options. Alter spacing units, font sizes, line heights, radius and more to personalize each theme to your liking.

Using layout tokens, you can ensure a uniform aesthetic across all components without needing to override the default Tailwind CSS configuration.

module.exports = {
  plugins: [
    nextui({
      layout: {}, // common layout options
      themes: {
        light: {
          layout: {}, // light theme layout options
          // ...
        },
        dark: {
          layout: {}, // dark theme layout options
          // ...
        },
        // ... custom themes
      },
    }),
  ],
};

Layout options are applied to all components.

Default Layout

Default values for the layout tokens are:

module.exports = {
  plugins: [
    nextui({
      layout: {
        spacingUnit: 4, // in px
        disabledOpacity: 0.5, // this value is applied as opacity-[value] when the component is disabled
        dividerWeight: "1px", // h-divider the default height applied to the divider component
        fontSize: {
          tiny: "0.75rem", // text-tiny
          small: "0.875rem", // text-small
          medium: "1rem", // text-medium
          large: "1.125rem", // text-large
        },
        lineHeight: {
          tiny: "1rem", // text-tiny
          small: "1.25rem", // text-small
          medium: "1.5rem", // text-medium
          large: "1.75rem", // text-large
        },
        radius: {
          small: "8px", // rounded-small
          medium: "12px", // rounded-medium
          large: "14px", // rounded-large
        },
        borderWidth: {
          small: "1px", // border-small
          medium: "2px", // border-medium (default)
          large: "3px", // border-large
        },
      },
      themes: {
        light: {
          hoverOpacity: 0.8, //  this value is applied as opacity-[value] when the component is hovered
          layout: {
            boxShadow: {
              // shadow-small
              small:
                "0px 0px 5px 0px rgb(0 0 0 / 0.02), 0px 2px 10px 0px rgb(0 0 0 / 0.06), 0px 0px 1px 0px rgb(0 0 0 / 0.3)",
              // shadow-medium
              medium:
                "0px 0px 15px 0px rgb(0 0 0 / 0.03), 0px 2px 30px 0px rgb(0 0 0 / 0.08), 0px 0px 1px 0px rgb(0 0 0 / 0.3)",
              // shadow-large
              large:
                "0px 0px 30px 0px rgb(0 0 0 / 0.04), 0px 30px 60px 0px rgb(0 0 0 / 0.12), 0px 0px 1px 0px rgb(0 0 0 / 0.3)",
            },
          },
        },
        dark: {
          layout: {
            hoverOpacity: 0.9, //  this value is applied as opacity-[value] when the component is hovered
            boxShadow: {
              // shadow-small
              small:
                "0px 0px 5px 0px rgb(0 0 0 / 0.05), 0px 2px 10px 0px rgb(0 0 0 / 0.2), inset 0px 0px 1px 0px rgb(255 255 255 / 0.15)",
              // shadow-medium
              medium:
                "0px 0px 15px 0px rgb(0 0 0 / 0.06), 0px 2px 30px 0px rgb(0 0 0 / 0.22), inset 0px 0px 1px 0px rgb(255 255 255 / 0.15)",
              // shadow-large
              large:
                "0px 0px 30px 0px rgb(0 0 0 / 0.07), 0px 30px 60px 0px rgb(0 0 0 / 0.26), inset 0px 0px 1px 0px rgb(255 255 255 / 0.15)",
            },
          },
        },
      },
    }),
  ],
};

Units

Units tokens define consistent spacing, padding, margin, gap and sizes across the components. Based on the spacingUnit token (default 4px), NextUI auto-generates the following units:

// spacingUnit = 4px
{
  'unit-xs': '8px', // 2 * spacingUnit
  'unit-sm': '12px', // 3 * spacingUnit
  'unit-md': '16px', // 4 * spacingUnit
  'unit-lg': '22px', // 5.5 * spacingUnit
  'unit-xl': '36px', // 9 * spacingUnit
  'unit-2xl': '48px', // 12 * spacingUnit
  'unit-3xl': '80px', // 20 * spacingUnit
  'unit-4xl': '120px', // 30 * spacingUnit
  'unit-5xl': '224px', // 56 * spacingUnit
  'unit-6xl': '288px', // 72 * spacingUnit
  'unit-7xl': '384px', // 96 * spacingUnit
  'unit-8xl': '512px', // 128 * spacingUnit
  'unit-9xl': '640px', // 160 * spacingUnit
  'unit-0': '0px', // 0 * spacingUnit
  'unit-1': '4px', // 1 * spacingUnit
  'unit-2': '8px', // 2 * spacingUnit
  'unit-3': '12px', // 3 * spacingUnit
  'unit-3_5': '14px' // 3.5 * spacingUnit
  'unit-4': '16px', // 4 * spacingUnit
  'unit-5': '20px', // 5 * spacingUnit
  'unit-6': '24px', // 6 * spacingUnit
  'unit-7': '28px', // 7 * spacingUnit
  'unit-8': '32px', // 8 * spacingUnit
  'unit-9': '36px', // 9 * spacingUnit
  'unit-10': '40px', // 10 * spacingUnit
  'unit-11': '44px', // 11 * spacingUnit
  'unit-12': '48px', // 12 * spacingUnit
  'unit-13': '52px', // 13 * spacingUnit
  'unit-14': '56px', // 14 * spacingUnit
  'unit-15': '60px', // 15 * spacingUnit
  'unit-16': '64px', // 16 * spacingUnit
  'unit-17': '68px', // 17 * spacingUnit
  'unit-18': '72px', // 18 * spacingUnit
  'unit-20': '80px', // 20 * spacingUnit
  'unit-24': '96px', // 24 * spacingUnit
  'unit-28': '112px', // 28 * spacingUnit
  'unit-32': '128px', // 32 * spacingUnit
  'unit-36': '144px', // 36 * spacingUnit
  'unit-40': '160px', // 40 * spacingUnit
  'unit-44': '176px', // 44 * spacingUnit
  'unit-48': '192px', // 48 * spacingUnit
  'unit-52': '208px', // 52 * spacingUnit
  'unit-56': '224px', // 56 * spacingUnit
  'unit-60': '240px', // 60 * spacingUnit
  'unit-64': '256px', // 64 * spacingUnit
  'unit-72': '288px', // 72 * spacingUnit
  'unit-80': '320px', // 80 * spacingUnit
  'unit-96': '384px', // 96 * spacingUnit
}

Using Units

NextUI units behave like Tailwind CSS spacing units. You can use them in the margin, padding, width, height, min-width, min-height, gap, top, right, bottom, and left properties.

import {Button} from "@nextui-org/react";


export const MyButton = () => {
  return (
    <Button className="px-unit-2 py-unit-1 min-w-unit-3xl">
      My Button
    </Button>
  );
};

Remember: Any changes to the spacingUnit token will automatically update the units.

CSS Variables

NextUI creates CSS variables using the format --prefix-prop-name-scale for each layout token. By default the prefix is nextui, but you can change it with the prefix option.

module.exports = {
  plugins: [
    nextui({
      prefix: "myapp",
    }),
  ],
};

Then you can use the CSS variables in your CSS files.

/* With default prefix */
.my-button {
  padding: var(--nextui-spacing-unit-4);
  font-size: var(--nextui-font-size-small);
  line-height: var(--nextui-line-height-small);
  border-radius: var(--nextui-radius-medium);
}
/*  With custom prefix */
.my-component {
  padding: var(--myapp-spacing-unit-4);
  font-size: var(--myapp-font-size-small);
  line-height: var(--myapp-line-height-small);
  border-radius: var(--myapp-radius-medium);
}

API Reference

AttributeTypeDescription
spacingUnitnumberBase unit token that defines a consistent spacing scale across the components.
disabledOpacitystring, numberA number between 0 and 1 that is applied as opacity-[value] when the component is disabled.
hoverOpacitystring, numberA number between 0 and 1 that is applied as opacity-[value] when the component is hovered.
dividerWeightstringThe default height applied to the divider component. We recommend to use px units.
fontSizeFontThemeUnitThe default font size applied across the components.
lineHeightFontThemeUnitThe default line height applied across the components.
radiusBaseThemeUnitThe default radius applied across the components. We recommend to use rem units.
borderWidthBaseThemeUnitThe border width applied across the components.
boxShadowBaseThemeUnitThe box shadow applied across the components.

BaseThemeUnit

export type BaseThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
};

FontThemeUnit

export type FontThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
  tiny?: string;
};
ThemeColors