Theme Configuration

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

// tailwind.config.js
module.exports = {
  theme: {
    fontFamily: {
      display: 'Gilroy',
      body: 'Graphik',
    },
    borderWidth: {
      default: '1px',
      '0': '0',
      '2': '2px',
      '4': '4px',
    },
    extend: {
      colors: {
        cyan: '#9cdbff',
      },
      spacing: {
        '96': '24rem',
        '128': '32rem',
      }
    }
  }
}

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; you’re encouraged to customize it as much as you need to to fit the goals of your design.

Theme structure

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

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

Colors

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

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      black: '#000',
      white: '#fff',
      gray: {
        100: '#f7fafc',
        // ...
        900: '#1a202c',
      },

      // ...
    }
  }
}

By default, these colors are inherited by the backgroundColor, textColor, and borderColor core plugins.

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
module.exports = {
  theme: {
    spacing: {
      px: '1px',
      '0': '0',
      '1': '0.25rem',
      '2': '0.5rem',
      '3': '0.75rem',
      '4': '1rem',
      '5': '1.25rem',
      '6': '1.5rem',
      '8': '2rem',
      '10': '2.5rem',
      '12': '3rem',
      '16': '4rem',
      '20': '5rem',
      '24': '6rem',
      '32': '8rem',
      '40': '10rem',
      '48': '12rem',
      '56': '14rem',
      '64': '16rem',
    }
  }
}

By default, these values are inherited by the padding, margin, negativeMargin, width, and height core styles.

To learn more, see the spacing customization documentation.

Core styles

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:

t.roundedNone { borderRadius: 0 }
t.roundedSm   { borderRadius: 2 }
t.rounded      { borderRadius: 4 }
t.roundedLg   { borderRadius: 8 }
t.roundedFull { borderRadius: 9999 }

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 supported by many (although not all) of the core styles.

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

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.

Overriding the default theme

To override an option in the default theme, create a theme section in your tailwind.config.js file and add the key you’d like to override.

// tailwind.config.js
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.

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.

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

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      // Adds a new spacing option in addition to the default spacing values
      spacing: {
        '128': '32rem',
      }
    }
  }
}

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
module.exports = {
  theme: {
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    },
    extend: {
      spacing: {
        '128': '32rem',
      }
    }
  }
}

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 a theme() function that you can use to look up other values in your theme using dot notation.

For example, you could generate borderColor utilities for every color in your color palette by referencing theme('colors') in your borderColor configuration:

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      // ...
    },
    borderColor: theme => theme('colors')
  }
}

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.

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,
        ]
      }
    }
  }
}

Adding your own keys

There are a number of situations where it can be useful to add your own keys to the theme object.

One example of this is adding new keys to create a single source of truth for values that are common between multiple core plugins. For example, you could extract a shared positions object that could be referenced by both the backgroundPosition and objectPosition plugins:

// tailwind.config.js
module.exports = {
  theme: {
    positions: {
      bottom: 'bottom',
      center: 'center',
      left: 'left',
      'left-bottom': 'left bottom',
      'left-top': 'left top',
      right: 'right',
      'right-bottom': 'right bottom',
      'right-top': 'right top',
      top: 'top',
    },
    backgroundPosition: theme => theme('positions'),
    objectPosition: theme => theme('positions'),
  }
}

Configuration reference

Key	Description
colors	Your project’s color palette
spacing	Your project’s spacing scale
backgroundColor	Values for the background-color property
borderColor	Values for the border-color property
borderRadius	Values for the border-radius property
borderStyle	Values for the border-style property
borderWidth	Values for the border-width property
boxShadow	Values for the box-shadow property
flex	Values for the flex 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
height	Values for the height property
inset	Values for the inset property
letterSpacing	Values for the letter-spacing property
lineHeight	Values for the line-height property
margin	Values for the margin 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
negativeMargin	Values for the negative-margin property
opacity	Values for the opacity property
padding	Values for the padding property
textColor	Values for the text-color property
width	Values for the width property
zIndex	Values for the z-index property