Customization

Theme Configuration

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

  1. module.exports = {
  2. theme: {
  3. screens: {
  4. sm: '480px',
  5. md: '768px',
  6. lg: '976px',
  7. xl: '1440px',
  8. },
  9. colors: {
  10. 'blue': '#1fb6ff',
  11. 'purple': '#7e5bef',
  12. 'pink': '#ff49db',
  13. 'orange': '#ff7849',
  14. 'green': '#13ce66',
  15. 'yellow': '#ffc82c',
  16. 'gray-dark': '#273444',
  17. 'gray': '#8492a6',
  18. 'gray-light': '#d3dce6',
  19. },
  20. fontFamily: {
  21. sans: ['Graphik', 'sans-serif'],
  22. serif: ['Merriweather', 'serif'],
  23. },
  24. extend: {
  25. spacing: {
  26. '128': '32rem',
  27. '144': '36rem',
  28. },
  29. borderRadius: {
  30. '4xl': '2rem',
  31. }
  32. }
  33. }
  34. }

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

  1. module.exports = {
  2. theme: {
  3. screens: {
  4. 'sm': '640px',
  5. 'md': '768px',
  6. 'lg': '1024px',
  7. 'xl': '1280px',
  8. '2xl': '1536px',
  9. }
  10. }
  11. }

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

  1. module.exports = {
  2. theme: {
  3. colors: {
  4. transparent: 'transparent',
  5. black: '#000',
  6. white: '#fff',
  7. gray: {
  8. 100: '#f7fafc',
  9. // ...
  10. 900: '#1a202c',
  11. },
  12. // ...
  13. }
  14. }
  15. }

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

  1. module.exports = {
  2. theme: {
  3. spacing: {
  4. px: '1px',
  5. 0: '0',
  6. 0.5: '0.125rem',
  7. 1: '0.25rem',
  8. 1.5: '0.375rem',
  9. 2: '0.5rem',
  10. 2.5: '0.625rem',
  11. 3: '0.75rem',
  12. 3.5: '0.875rem',
  13. 4: '1rem',
  14. 5: '1.25rem',
  15. 6: '1.5rem',
  16. 7: '1.75rem',
  17. 8: '2rem',
  18. 9: '2.25rem',
  19. 10: '2.5rem',
  20. 11: '2.75rem',
  21. 12: '3rem',
  22. 14: '3.5rem',
  23. 16: '4rem',
  24. 20: '5rem',
  25. 24: '6rem',
  26. 28: '7rem',
  27. 32: '8rem',
  28. 36: '9rem',
  29. 40: '10rem',
  30. 44: '11rem',
  31. 48: '12rem',
  32. 52: '13rem',
  33. 56: '14rem',
  34. 60: '15rem',
  35. 64: '16rem',
  36. 72: '18rem',
  37. 80: '20rem',
  38. 96: '24rem',
  39. },
  40. }
  41. }

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:

  1. module.exports = {
  2. theme: {
  3. borderRadius: {
  4. 'none': '0',
  5. 'sm': '.125rem',
  6. DEFAULT: '.25rem',
  7. 'lg': '.5rem',
  8. 'full': '9999px',
  9. },
  10. }
  11. }

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:

  1. .rounded-none { border-radius: 0 }
  2. .rounded-sm { border-radius: .125rem }
  3. .rounded { border-radius: .25rem }
  4. .rounded-lg { border-radius: .5rem }
  5. .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 extend key in the theme section of your configuration file.

For example, if you wanted to add an extra breakpoint but preserve the existing ones, you could extend the screens property:

tailwind.config.js

  1. module.exports = {
  2. theme: {
  3. extend: {
  4. // Adds a new breakpoint in addition to the default breakpoints
  5. screens: {
  6. '3xl': '1600px',
  7. }
  8. }
  9. }
  10. }

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

  1. module.exports = {
  2. theme: {
  3. // Replaces all of the default `opacity` values
  4. opacity: {
  5. '0': '0',
  6. '20': '0.2',
  7. '40': '0.4',
  8. '60': '0.6',
  9. '80': '0.8',
  10. '100': '1',
  11. }
  12. }
  13. }

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

  1. module.exports = {
  2. theme: {
  3. opacity: {
  4. '0': '0',
  5. '20': '0.2',
  6. '40': '0.4',
  7. '60': '0.6',
  8. '80': '0.8',
  9. '100': '1',
  10. },
  11. extend: {
  12. screens: {
  13. '3xl': '1600px',
  14. }
  15. }
  16. }
  17. }

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

  1. module.exports = {
  2. theme: {
  3. spacing: {
  4. // ...
  5. },
  6. backgroundSize: ({ theme }) => ({
  7. auto: 'auto',
  8. cover: 'cover',
  9. contain: 'contain',
  10. ...theme('spacing')
  11. })
  12. }
  13. }

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.

Theme - 图1

You can’t use functions for individual values

tailwind.config.js

  1. module.exports = {
  2. theme: {
  3. fill: {
  4. gray: ({ theme }) => theme('colors.gray')
  5. }
  6. }
  7. }

Theme - 图2

Use functions for top-level theme keys

tailwind.config.js

  1. module.exports = {
  2. theme: {
  3. fill: ({ theme }) => ({
  4. gray: theme('colors.gray')
  5. })
  6. }
  7. }

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

  1. const defaultTheme = require('tailwindcss/defaultTheme')
  2. module.exports = {
  3. theme: {
  4. extend: {
  5. fontFamily: {
  6. sans: [
  7. 'Lato',
  8. ...defaultTheme.fontFamily.sans,
  9. ]
  10. }
  11. }
  12. }
  13. }

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.

Theme - 图3

Don’t assign an empty object in your theme configuration

tailwind.config.js

  1. module.exports = {
  2. theme: {
  3. opacity: {},
  4. }
  5. }

Theme - 图4

Do disable the plugin in your corePlugins configuration

tailwind.config.js

  1. module.exports = {
  2. corePlugins: {
  3. opacity: false,
  4. }
  5. }

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.

KeyDescription
screensYour project’s responsive breakpoints
supportsValues for the supports property
colorsYour project’s color palette
columnsValues for the columns property
spacingYour project’s spacing scale
animationValues for the animation property
ariaValues for the aria property
aspectRatioValues for the aspect-ratio property
backdropBlurValues for the backdropBlur plugin
backdropBrightnessValues for the backdropBrightness plugin
backdropContrastValues for the backdropContrast plugin
backdropGrayscaleValues for the backdropGrayscale plugin
backdropHueRotateValues for the backdropHueRotate plugin
backdropInvertValues for the backdropInvert plugin
backdropOpacityValues for the backdropOpacity plugin
backdropSaturateValues for the backdropSaturate plugin
backdropSepiaValues for the backdropSepia plugin
backgroundColorValues for the background-color property
backgroundImageValues for the background-image property
backgroundOpacityValues for the background-opacity property
backgroundPositionValues for the background-position property
backgroundSizeValues for the background-size property
blurValues for the blur plugin
brightnessValues for the brightness plugin
borderColorValues for the border-color property
borderOpacityValues for the borderOpacity plugin
borderRadiusValues for the border-radius property
borderSpacingValues for the border-spacing property
borderWidthValues for the borderWidth plugin
boxShadowValues for the box-shadow property
boxShadowColorValues for the boxShadowColor plugin
caretColorValues for the caret-color property
accentColorValues for the accent-color property
contrastValues for the contrast plugin
containerConfiguration for the container plugin
contentValues for the content property
cursorValues for the cursor property
divideColorValues for the divideColor plugin
divideOpacityValues for the divideOpacity plugin
divideWidthValues for the divideWidth plugin
dropShadowValues for the dropShadow plugin
fillValues for the fill plugin
grayscaleValues for the grayscale plugin
hueRotateValues for the hueRotate plugin
invertValues for the invert plugin
flexValues for the flex property
flexBasisValues for the flex-basis property
flexGrowValues for the flex-grow property
flexShrinkValues for the flex-shrink property
fontFamilyValues for the font-family property
fontSizeValues for the font-size property
fontWeightValues for the font-weight property
gapValues for the gap property
gradientColorStopsValues for the gradientColorStops plugin
gridAutoColumnsValues for the grid-auto-columns property
gridAutoRowsValues for the grid-auto-rows property
gridColumnValues for the grid-column property
gridColumnEndValues for the grid-column-end property
gridColumnStartValues for the grid-column-start property
gridRowValues for the grid-row property
gridRowStartValues for the grid-row-start property
gridRowEndValues for the grid-row-end property
gridTemplateColumnsValues for the grid-template-columns property
gridTemplateRowsValues for the grid-template-rows property
heightValues for the height property
insetValues for the top, right, bottom, and left properties
keyframesKeyframe values used in the animation plugin
letterSpacingValues for the letter-spacing property
lineHeightValues for the line-height property
listStyleTypeValues for the list-style-type property
marginValues for the margin property
maxHeightValues for the max-height property
maxWidthValues for the max-width property
minHeightValues for the min-height property
minWidthValues for the min-width property
objectPositionValues for the object-position property
opacityValues for the opacity property
orderValues for the order property
paddingValues for the padding property
placeholderColorValues for the placeholderColor plugin
placeholderOpacityValues for the placeholderOpacity plugin
outlineColorValues for the outline-color property
outlineOffsetValues for the outline-offset property
outlineWidthValues for the outline-width property
ringColorValues for the ringColor plugin
ringOffsetColorValues for the ringOffsetColor plugin
ringOffsetWidthValues for the ringOffsetWidth plugin
ringOpacityValues for the ringOpacity plugin
ringWidthValues for the ringWidth plugin
rotateValues for the rotate plugin
saturateValues for the saturate plugin
scaleValues for the scale plugin
scrollMarginValues for the scroll-margin property
scrollPaddingValues for the scroll-padding property
sepiaValues for the sepia plugin
skewValues for the skew plugin
spaceValues for the space plugin
strokeValues for the stroke property
strokeWidthValues for the stroke-width property
textColorValues for the text-color property
textDecorationColorValues for the text-decoration-color property
textDecorationThicknessValues for the text-decoration-thickness property
textUnderlineOffsetValues for the text-underline-offset property
textIndentValues for the text-indent property
textOpacityValues for the textOpacity plugin
transformOriginValues for the transform-origin property
transitionDelayValues for the transition-delay property
transitionDurationValues for the transition-duration property
transitionPropertyValues for the transition-property property
transitionTimingFunctionValues for the transition-timing-function property
translateValues for the translate plugin
widthValues for the width property
willChangeValues for the will-change property
zIndexValues for the z-index property