Question

Customizing the default theme for your project.

The theme section of your tailwind.config.js file is where you define your project’s color palette, type scale, fonts, breakpoints, border radius values, and more.

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    screens: {
      sm: '480px',
      md: '768px',
      lg: '976px',
      xl: '1440px',
    },
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

We provide a sensible default theme with a very generous set of values to get you started, but don’t be afraid to change it or extend it; you’re encouraged to customize it as much as you need to fit the goals of your design.

---

Theme structure

The theme object contains keys for screens, colors, and spacing, as well as a key for each customizable core plugin.

See the theme configuration reference or the default theme for a complete list of theme options.

Screens

The screens key allows you to customize the responsive breakpoints in your project.

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    screens: {
      'sm': '640px',
      'md': '768px',
      'lg': '1024px',
      'xl': '1280px',
      '2xl': '1536px',
    }
  }
}

To learn more, see the breakpoint customization documentation.

Colors

The colors key allows you to customize the global color palette for your project.

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      black: '#000',
      white: '#fff',
      gray: {
        100: '#f7fafc',
        // ...
        900: '#1a202c',
      },

      // ...
    }
  }
}

By default, these colors are inherited by all color-related core plugins, like backgroundColor, borderColor, textColor, and others.

To learn more, see the color customization documentation.

Spacing

The spacing key allows you to customize the global spacing and sizing scale for your project.

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    spacing: {
      px: '1px',
      0: '0',
      0.5: '0.125rem',
      1: '0.25rem',
      1.5: '0.375rem',
      2: '0.5rem',
      2.5: '0.625rem',
      3: '0.75rem',
      3.5: '0.875rem',
      4: '1rem',
      5: '1.25rem',
      6: '1.5rem',
      7: '1.75rem',
      8: '2rem',
      9: '2.25rem',
      10: '2.5rem',
      11: '2.75rem',
      12: '3rem',
      14: '3.5rem',
      16: '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',
    },
  }
}

By default, these values are inherited by the padding, margin, width, height, maxHeight, flex-basis, gap, inset, space, translate, scrollMargin, scrollPadding, and textIndent core plugins.

To learn more, see the spacing customization documentation.

Core plugins

The rest of the theme section is used to configure which values are available for each individual core plugin.

For example, the borderRadius key lets you customize which border radius utilities will be generated:

module.exports = {
  theme: {
    borderRadius: {
      'none': '0',
      'sm': '.125rem',
      DEFAULT: '.25rem',
      'lg': '.5rem',
      'full': '9999px',
    },
  }
}

The keys determine the suffix for the generated classes, and the values determine the value of the actual CSS declaration.

The example borderRadius configuration above would generate the following CSS classes:

.rounded-none { border-radius: 0 }
.rounded-sm   { border-radius: .125rem }
.rounded      { border-radius: .25rem }
.rounded-lg   { border-radius: .5rem }
.rounded-full { border-radius: 9999px }

You’ll notice that using a key of DEFAULT in the theme configuration created the class rounded with no suffix. This is a common convention in Tailwind and is supported by all core plugins.

To learn more about customizing a specific core plugin, visit the documentation for that plugin.

For a complete reference of available theme properties and their default values, see the default theme configuration.

---

Customizing the default theme

Out of the box, your project will automatically inherit the values from the default theme configuration. If you would like to customize the default theme, you have a few different options depending on your goals.

Extending the default theme

If you’d like to preserve the default values for a theme option but also add new values, add your extensions under the theme.extend key in your configuration file. Values under this key are merged with existing theme values and automatically become available as new classes that you can use.

As an example, here we extend the fontFamily property to add the font-display class that can change the font used on an element:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        display: 'Oswald, ui-serif', // Adds a new `font-display` class
      }
    }
  }
}

After adding this to your theme you can use it just like any other font family utility:

<h1 class="font-display">
  This uses the Oswald font
</h1>

In some cases, properties map to variants that can be placed in front of a utility to conditionally apply its styles. For example, to add a 3xl screen size that works just like the existing responsive screens, add a property under the screens key:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      screens: {
        '3xl': '1600px', // Adds a new `3xl:` screen variant
      }
    }
  }
}

With this addition, a new 3xl screen size is made available alongside the existing responsive variants like sm, md, lg, etc. You can use this new variant by placing it before a utility class:

<blockquote class="text-base md:text-md 3xl:text-lg">
  Oh I gotta get on that internet, I'm late on everything!
</blockquote>

Overriding the default theme

To override an option in the default theme, add your overrides directly under the theme section of your tailwind.config.js:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // Replaces all of the default `opacity` values
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    }
  }
}

This will completely replace Tailwind’s default configuration for that key, so in the example above none of the default opacity utilities would be generated.

Any keys you do not provide will be inherited from the default theme, so in the above example, the default theme configuration for things like colors, spacing, border-radius, background-position, etc. would be preserved.

You can of course both override some parts of the default theme and extend other parts of the default theme within the same configuration:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    },
    extend: {
      screens: {
        '3xl': '1600px',
      }
    }
  }
}

Referencing other values

If you need to reference another value in your theme, you can do so by providing a closure instead of a static value. The closure will receive an object that includes a theme() function that you can use to look up other values in your theme using dot notation.

For example, you could generate background-size utilities for every value in your spacing scale by referencing theme('spacing') in your backgroundSize configuration:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    spacing: {
      // ...
    },
    backgroundSize: ({ theme }) => ({
      auto: 'auto',
      cover: 'cover',
      contain: 'contain',
      ...theme('spacing')
    })
  }
}

The theme() function attempts to find the value you are looking for from the fully merged theme object, so it can reference your own customizations as well as the default theme values. It also works recursively, so as long as there is a static value at the end of the chain it will be able to resolve the value you are looking for.

Note that you can only use this kind of closure with top-level theme keys, not the keys inside of each section.

You can’t use functions for individual values

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    fill: {
      gray: ({ theme }) => theme('colors.gray')
    }
  }
}

Use functions for top-level theme keys

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    fill: ({ theme }) => ({
      gray: theme('colors.gray')
    })
  }
}

Referencing the default theme

If you’d like to reference a value in the default theme for any reason, you can import it from tailwindcss/defaultTheme.

One example of where this is useful is if you’d like to add a font family to one of Tailwind’s default font stacks:

tailwind.config.js

const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: [
          'Lato',
          ...defaultTheme.fontFamily.sans,
        ]
      }
    }
  }
}

Disabling an entire core plugin

If you don’t want to generate any classes for a certain core plugin, it’s better to set that plugin to false in your corePlugins configuration than to provide an empty object for that key in your theme configuration.

Don’t assign an empty object in your theme configuration

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    opacity: {},
  }
}

Do disable the plugin in your corePlugins configuration

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: {
    opacity: false,
  }
}

The end result is the same, but since many core plugins expose no configuration they can only be disabled using corePlugins anyways, so it’s better to be consistent.

---

Configuration reference

Except for screens, colors, and spacing, all of the keys in the theme object map to one of Tailwind’s core plugins. Since many plugins are responsible for CSS properties that only accept a static set of values (like float for example), note that not every plugin has a corresponding key in the theme object.

All of these keys are also available under the theme.extend key to enable extending the default theme.

Key	Description
accentColor	Values for the accent-color property
animation	Values for the animation property
aria	Values for the aria property
aspectRatio	Values for the aspect-ratio property
backdropBlur	Values for the backdropBlur plugin
backdropBrightness	Values for the backdropBrightness plugin
backdropContrast	Values for the backdropContrast plugin
backdropGrayscale	Values for the backdropGrayscale plugin
backdropHueRotate	Values for the backdropHueRotate plugin
backdropInvert	Values for the backdropInvert plugin
backdropOpacity	Values for the backdropOpacity plugin
backdropSaturate	Values for the backdropSaturate plugin
backdropSepia	Values for the backdropSepia plugin
backgroundColor	Values for the background-color property
backgroundImage	Values for the background-image property
backgroundOpacity	Values for the background-opacity property
backgroundPosition	Values for the background-position property
backgroundSize	Values for the background-size property
blur	Values for the blur plugin
borderColor	Values for the border-color property
borderOpacity	Values for the borderOpacity plugin
borderRadius	Values for the border-radius property
borderSpacing	Values for the border-spacing property
borderWidth	Values for the borderWidth plugin
boxShadow	Values for the box-shadow property
boxShadowColor	Values for the boxShadowColor plugin
brightness	Values for the brightness plugin
caretColor	Values for the caret-color property
colors	Your project's color palette
columns	Values for the columns property
container	Configuration for the container plugin
content	Values for the content property
contrast	Values for the contrast plugin
cursor	Values for the cursor property
divideColor	Values for the divideColor plugin
divideOpacity	Values for the divideOpacity plugin
divideWidth	Values for the divideWidth plugin
dropShadow	Values for the dropShadow plugin
fill	Values for the fill plugin
flex	Values for the flex property
flexBasis	Values for the flex-basis property
flexGrow	Values for the flex-grow property
flexShrink	Values for the flex-shrink property
fontFamily	Values for the font-family property
fontSize	Values for the font-size property
fontWeight	Values for the font-weight property
gap	Values for the gap property
gradientColorStops	Values for the gradientColorStops plugin
gradientColorStopPositions	Values for the gradient-color-stop-positions property
grayscale	Values for the grayscale plugin
gridAutoColumns	Values for the grid-auto-columns property
gridAutoRows	Values for the grid-auto-rows property
gridColumn	Values for the grid-column property
gridColumnEnd	Values for the grid-column-end property
gridColumnStart	Values for the grid-column-start property
gridRow	Values for the grid-row property
gridRowEnd	Values for the grid-row-end property
gridRowStart	Values for the grid-row-start property
gridTemplateColumns	Values for the grid-template-columns property
gridTemplateRows	Values for the grid-template-rows property
height	Values for the height property
hueRotate	Values for the hueRotate plugin
inset	Values for the top, right, bottom, and left properties
invert	Values for the invert plugin
keyframes	Keyframe values used in the animation plugin
letterSpacing	Values for the letter-spacing property
lineHeight	Values for the line-height property
listStyleType	Values for the list-style-type property
listStyleImage	Values for the list-style-image property
margin	Values for the margin property
lineClamp	Values for the line-clamp property
maxHeight	Values for the max-height property
maxWidth	Values for the max-width property
minHeight	Values for the min-height property
minWidth	Values for the min-width property
objectPosition	Values for the object-position property
opacity	Values for the opacity property
order	Values for the order property
outlineColor	Values for the outline-color property
outlineOffset	Values for the outline-offset property
outlineWidth	Values for the outline-width property
padding	Values for the padding property
placeholderColor	Values for the placeholderColor plugin
placeholderOpacity	Values for the placeholderOpacity plugin
ringColor	Values for the ringColor plugin
ringOffsetColor	Values for the ringOffsetColor plugin
ringOffsetWidth	Values for the ringOffsetWidth plugin
ringOpacity	Values for the ringOpacity plugin
ringWidth	Values for the ringWidth plugin
rotate	Values for the rotate plugin
saturate	Values for the saturate plugin
scale	Values for the scale plugin
screens	Your project's responsive breakpoints
scrollMargin	Values for the scroll-margin property
scrollPadding	Values for the scroll-padding property
sepia	Values for the sepia plugin
skew	Values for the skew plugin
space	Values for the space plugin
spacing	Your project's spacing scale
stroke	Values for the stroke property
strokeWidth	Values for the stroke-width property
supports	Values for the supports property
data	Values for the data property
textColor	Values for the color property
textDecorationColor	Values for the text-decoration-color property
textDecorationThickness	Values for the text-decoration-thickness property
textIndent	Values for the text-indent property
textOpacity	Values for the textOpacity plugin
textUnderlineOffset	Values for the text-underline-offset property
transformOrigin	Values for the transform-origin property
transitionDelay	Values for the transition-delay property
transitionDuration	Values for the transition-duration property
transitionProperty	Values for the transition-property property
transitionTimingFunction	Values for the transition-timing-function property
translate	Values for the translate plugin
size	Values for the size property
width	Values for the width property
willChange	Values for the will-change property
zIndex	Values for the z-index property