A guide to configuring and customizing your Tailwind installation.

Because Tailwind is a framework for building bespoke user interfaces, it has been designed from the ground up with customization in mind.

By default, Tailwind will look for an optional tailwind.config.js file at the root of your project where you can define any customizations.

// Example `tailwind.config.js` file

module.exports = {
  important: true,
  theme: {
    fontFamily: {
      display: ['Gilroy', 'sans-serif'],
      body: ['Graphik', 'sans-serif'],
    extend: {
      colors: {
        cyan: '#9cdbff',
      margin: {
        '96': '24rem',
        '128': '32rem',
  variants: {
    opacity: ['responsive', 'hover']

Every section of the config file is optional, so you only have to specify what you'd like to change. Any missing sections will fall back to Tailwind's default configuration.

Creating your configuration file

Generate a Tailwind config file for your project using the Tailwind CLI utility included when you install the tailwindcss npm package:

npx tailwindcss init

This will create a minimal tailwind.config.js file at the root of your project:

// tailwind.config.js
module.exports = {
  theme: {},
  variants: {},
  plugins: [],

Using a different file name

To use a name other than tailwind.config.js, pass it as an argument on the command-line:

npx tailwindcss init tailwindcss-config.js

If you use a custom file name, you will need to specify it when including Tailwind as a plugin in your PostCSS configuration as well:

// postcss.config.js
module.exports = {
  plugins: [

Scaffolding the entire default configuration

For most users we encourage you to keep your config file as minimal as possible, and only specify the things you want to customize.

If you'd rather scaffold a complete configuration file that includes all of Tailwind's default configuration, use the --full option:

npx tailwindcss init --full

You'll get a file that matches the default configuration file Tailwind uses internally.


The theme section is where you define your color palette, font stacks, type scale, border sizes, breakpoints — anything related to the visual design of your site.

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
    fontFamily: {
      display: ['Gilroy', 'sans-serif'],
      body: ['Graphik', 'sans-serif'],
    borderWidth: {
      default: '1px',
      '0': '0',
      '2': '2px',
      '4': '4px',
    extend: {
      colors: {
        cyan: '#9cdbff',
      spacing: {
        '96': '24rem',
        '128': '32rem',

Learn more about the default theme and how to customize it in the theme configuration guide.


The variants section lets you control which variants are generated for each core utility plugin.

// tailwind.config.js
module.exports = {
  variants: {
    appearance: ['responsive'],
    backgroundColor: ['responsive', 'hover', 'focus'],
    fill: [],

Learn more in the variants configuration guide.


The plugins section allows you to register third-party plugins with Tailwind that can be used to generate extra utilities, components, base styles, or custom variants.

// tailwind.config.js
module.exports = {
  plugins: [

Learn more about writing your own plugins in the plugin authoring guide.


The prefix option allows you to add a custom prefix to all of Tailwind's generated utility classes. This can be really useful when layering Tailwind on top of existing CSS where there might be naming conflicts.

For example, you could add a tw- prefix by setting the prefix option like so:

// tailwind.config.js
module.exports = {
  prefix: 'tw-',

Now every utility will be generated with the configured prefix:

.tw-text-left {
  text-align: left;
.tw-text-center {
  text-align: center;
.tw-text-right {
  text-align: right;
/* etc. */

It's important to understand that this prefix is added to the beginning of each utility name, not to the entire class name.

That means that classes with responsive or state prefixes like sm: or hover: will still have the responsive or state prefix first, with your custom prefix appearing after the colon:

<div class="tw-text-lg md:tw-text-xl tw-bg-red-500 hover:tw-bg-blue-500">
  <!-- -->

Prefixes are only added to classes generated by Tailwind; no prefix will be added to your own custom classes.

That means if you add your own responsive utility like this:

@responsive  {
  .bg-brand-gradient { /* ... */ }

...the generated responsive classes will not have your configured prefix:

.bg-brand-gradient { /* ... */ }
@media (min-width: 640px) {
  .sm\:bg-brand-gradient { /* ... */ }
@media (min-width: 768px) {
  .md\:bg-brand-gradient { /* ... */ }
@media (min-width: 992) {
  .lg\:bg-brand-gradient { /* ... */ }
@media (min-width: 1280px) {
  .xl\:bg-brand-gradient { /* ... */ }

If you'd like to prefix your own utilities as well, just add the prefix to the class definition:

@responsive  {
  .tw-bg-brand-gradient { /* ... */ }


The important option lets you control whether or not Tailwind's utilities should be marked with !important. This can be really useful when using Tailwind with existing CSS that has high specificity selectors.

To generate utilities as !important, set the important key in your configuration options to true:

// tailwind.config.js
module.exports = {
  important: true,

Now all of Tailwind's utility classes will be generated as !important:

.leading-none {
  line-height: 1 !important;
.leading-tight {
  line-height: 1.25 !important;
.leading-snug {
  line-height: 1.375 !important;
/* etc. */

Note that any of your own custom utilities will not automatically be marked as !important by enabling this option.

If you'd like to make your own utilities !important, just add !important to the end of each declaration yourself:

@responsive  {
  .bg-brand-gradient {
    background-image: linear-gradient(#3490dc, #6574cd) !important;

Setting important to true is useful, but can introduce some issues when incorporating third-party JS libraries that add inline styles to your elements—in those cases, Tailwind's !important utilities defeat the inline styles. This is really common with animation libraries, for example.

If you're not facing that issue, feel free to skip to the next section! But if you are facing that issue, you can make utilities "important" in a less aggressive manner by providing a CSS selector instead of a boolean to the important option:

// tailwind.config.js
module.exports = {
  important: '#app',

This configuration will prefix all of your utilities with the given selector, effectively increasing their specificity without actually making them !important.

After you specifify the important selector, you'll need to ensure that the root element of your site matches it. Using the example above, we would need to set our root element's id attribute to app in order for styles to work properly.

After your configuration is all set up and your root element matches the selector in your Tailwind config, all of Tailwind's utilities will have a high enough specificity to defeat other classes used in your project, without interfering with inline styles:

<!-- ... -->
  .high-specificity .nested .selector {
    color: blue;
<body id="app">
  <div class="high-specificity">
    <div class="nested">
      <!-- Will be red-500 -->
      <div class="selector text-red-500"><!-- ... --></div>

  <!-- Will be #bada55 -->
  <div class="text-red-500" style="color: #bada55;"><!-- ... --></div>


The separator option lets you customize what character or string should be used to separate variant prefixes (screen sizes, hover, focus, etc.) from utility names (text-center, items-end, etc.).

We use a colon by default (:), but it can be useful to change this if you're using a templating language like Pug that doesn't support special characters in class names.

// tailwind.config.js
module.exports = {
  separator: '_',

Core Plugins

The corePlugins section lets you completely disable classes that Tailwind would normally generate by default if you don't need them for your project.

If you don't provide any corePlugins configuration, all core plugins will be enabled by default:

// tailwind.config.js
module.exports = {}

If you'd like to disable specific core plugins, provide an object for corePlugins that sets those plugins to false:

// tailwind.config.js
module.exports = {
  corePlugins: {
    float: false,
    objectFit: false,
    objectPosition: false,

If you'd like to whitelist which core plugins should be enabled, provide an array that includes a list of the core plugins you'd like to use:

// tailwind.config.js
module.exports = {
  corePlugins: [
    // ...

If you'd like to disable all of Tailwind's core plugins and simply use Tailwind as a tool for processing your own custom plugins, provide an empty array:

// tailwind.config.js
module.exports = {
  corePlugins: []

Here's a list of every core plugin for reference:

Core Plugin Description
preflight Tailwind's base/reset styles
container The container component
accessibility The sr-only and not-sr-only utilities
alignContent The align-content utilities like content-between
alignItems The align-items utilities like items-start
alignSelf The align-self utilities like self-end
appearance The appearance utilities like appearance-none
backgroundAttachment The background-attachment utilities like bg-fixed
backgroundColor The background-color utilities like bg-gray-200
backgroundOpacity The background-color opacity utilities like bg-opacity-25
backgroundPosition The background-position utilities like bg-center
backgroundRepeat The background-repeat utilities like bg-no-repeat
backgroundSize The background-size utilities like bg-cover
borderCollapse The border-collapse utilities like border-separate
borderColor The border-color utilities like border-gray-300
borderOpacity The border-color opacity utilities like border-opacity-25
borderRadius The border-radius utilities like rounded-lg
borderStyle The border-style utilities like border-dashed
borderWidth The border-width utilities like border-2
boxSizing The box-sizing utilities like box-border
boxShadow The box-shadow utilities like shadow-xl
clear The clear utilities like clear-left
cursor The cursor utilities like cursor-pointer
display The display utilities like block
divideColor The between elements border-color utilities like divide-gray-500
divideWidth The between elements border-width utilities like divide-x-2
fill The fill utilities like fill-current
flex The flex utilities like flex-1
flexDirection The flex-direction utilities like flex-col
flexGrow The flex-grow utilities like flex-grow-0
flexShrink The flex-shrink utilities like flex-shrink-0
flexWrap The flex-wrap utilities like flex-no-wrap
float The float utilities like float-left
gap The gap utilities like gap-4
gridAutoFlow The grid-auto-flow utilities like grid-flow-col
gridColumn The grid-column utilities like col-span-6
gridColumnStart The grid-column-start utilities like col-start-1
gridColumnEnd The grid-column-end utilities like col-end-4
gridRow The grid-row utilities like row-span-6
gridRowStart The grid-row-start utilities like row-start-1
gridRowEnd The grid-row-end utilities like row-end-4
gridTemplateColumns The grid-template-columns utilities like grid-cols-4
gridTemplateRows The grid-template-rows utilities like grid-rows-4
fontFamily The font-family utilities like font-sans
fontSize The font-size utilities like text-xl
fontSmoothing The font-smoothing utilities like antialiased
fontStyle The font-style utilities like italic
fontWeight The font-weight utilities like font-bold
height The height utilities like h-8
inset The inset utilities like top-0
justifyContent The justify-content utilities like justify-between
letterSpacing The letter-spacing utilities like tracking-tight
lineHeight The line-height utilities like leading-normal
listStylePosition The list-style-position utilities like list-inside
listStyleType The list-style-type utilities like list-disc
margin The margin utilities like mt-4
maxHeight The max-height utilities like max-h-screen
maxWidth The max-width utilities like max-w-full
minHeight The min-height utilities like min-h-screen
minWidth The min-width utilities like min-w-0
objectFit The object-fit utilities like object-cover
objectPosition The object-position utilities like object-center
opacity The opacity utilities like opacity-50
order The flexbox order utilities like order-last
outline The outline utilities like outline-none
overflow The overflow utilities like overflow-hidden
padding The padding utilities like py-12
placeholderColor The placeholder color utilities like placeholder-red-600
placeholderOpacity The placeholder color opacity utilities like placeholder-opacity-25
pointerEvents The pointer-events utilities like pointer-events-none
position The position utilities like absolute
resize The resize utilities like resize-y
rotate The rotate utilities like rotate-90
scale The scale utilities like scale-150
skew The skew utilities like skew-y-3
space The "space-between" utilities like space-x-4
stroke The stroke utilities like stroke-current
strokeWidth The stroke-width utilities like stroke-2
tableLayout The table-layout utilities like table-fixed
textAlign The text-align utilities like text-center
textColor The text-color utilities like text-red-600
textOpacity The text-color opacity utilities like text-opacity-25
textDecoration The text-decoration utilities like underline
textTransform The text-transform utilities like uppercase
transform The transform utility (for enabling transform features)
transitionDuration The transition-duration utilities like duration-100
transitionProperty The transition-property utilities like transition-colors
transitionTimingFunction The transition-timing-function utilities like ease-in-out
translate The translate utilities like translate-y-6
userSelect The user-select utilities like user-select-none
verticalAlign The vertical-align utilities like align-middle
visibility The visibility utilities like invisible
whitespace The whitespace utilities like whitespace-no-wrap
width The width utilities like w-1/2
wordBreak The word-break utilities like break-all
zIndex The z-index utilities like z-50

Referencing in JavaScript

It can often be useful to reference your configuration values in your own client-side JavaScript — for example to access some of your theme values when dynamically applying inline styles in a React or Vue component.

To make this easy, Tailwind provides a resolveConfig helper you can use to generate a fully merged version of your configuration object:

import resolveConfig from 'tailwindcss/resolveConfig'
import tailwindConfig from './tailwind.config.js'

const fullConfig = resolveConfig(tailwindConfig)

// => '1rem'
// => '768px'

// => '0 25px 50px -12px rgba(0, 0, 0, 0.25)'