W3cubDocs

/Tailwind CSS

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.

tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    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: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  },
}

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 = {
  content: [],
  theme: {
    extend: {},
  },
  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

When you use a custom file name, you will need to specify it as a command-line argument when compiling your CSS with the Tailwind CLI tool:

npx tailwindcss -c ./tailwindcss-config.js -i input.css -o output.css

If you’re using Tailwind as a PostCSS plugin, you will need to specify your custom configuration path in your PostCSS configuration:

postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: { config: './tailwindcss-config.js' },
  },
}

Alternatively, you can specify your custom configuration path using the @config directive:

@config "./tailwindcss-config.js";

@tailwind base;
@tailwind components;
@tailwind utilities;

Learn more about the @config directive in the Functions & Directives documentation.

Generating a PostCSS configuration file

Use the -p flag if you’d like to also generate a basic postcss.config.js file alongside your tailwind.config.js file:

npx tailwindcss init -p

This will generate a postcss.config.js file in your project that looks like this:

postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

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.

Configuration options

Content

The content section is where you configure the paths to all of your HTML templates, JS components, and any other files that contain Tailwind class names.

tailwind.config.js
module.exports = {
  content: [
    './pages/**/*.{html,js}',
    './components/**/*.{html,js}',
  ],
  // ...
}

Learn more about configuring your content sources in the Content Configuration documentation.

Theme

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

tailwind.config.js
module.exports = {
  // ...
  theme: {
    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: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

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

Plugins

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

tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/typography'),
    require('tailwindcss-children'),
  ],
}

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

Presets

The presets section allows you to specify your own custom base configuration instead of using Tailwind’s default base configuration.

tailwind.config.js
module.exports = {
  // ...
  presets: [
    require('@acmecorp/base-tailwind-config')
  ],

  // Project-specific customizations
  theme: {
    //...
  },
}

Learn more about presets in the presets documentation.

Prefix

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 class 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 after any variant modifiers. That means that classes with responsive or state modifiers like sm: or hover: will still have the responsive or state modifier 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">
  <!-- -->
</div>

The dash modifier for negative values should be added before your prefix, so -mt-8 would become -tw-mt-8 if you’ve configured tw- as your prefix:

<div class="-tw-mt-8">
  <!-- -->
</div>

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 custom utility like this:

@layer utilities {
  .bg-brand-gradient { /* ... */ }
}

…the generated variants will not have your configured prefix:

.bg-brand-gradient { /* ... */ }
.hover\:bg-brand-gradient:hover { /* ... */ }

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

@layer utilities {
  .tw-bg-brand-gradient { /* ... */ }
}

Important

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. */

This also applies to any custom utilities you define in your CSS using the @layer utilities directive:

/* Input */
@layer utilities {
  .bg-brand-gradient {
    background-image: linear-gradient(#3490dc, #6574cd);
  }
}

/* Output */
.bg-brand-gradient {
  background-image: linear-gradient(#3490dc, #6574cd) !important;
}

Selector strategy

Setting important to true 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, which can break your intended design.

To get around this, you can set important to an ID selector like #app instead:

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 specify 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:

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

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

When using the selector strategy, be sure that the template file that includes your root selector is included in your content configuration, otherwise all of your CSS will be removed when building for production.

Important modifier

Alternatively, you can make any utility important by adding a ! character to the beginning:

<p class="font-bold !font-medium">
  This will be medium even though bold comes later in the CSS.
</p>

The ! always goes at the beginning of the utility name, after any variants, but before any prefix:

<div class="sm:hover:!tw-font-bold">

This can be useful in rare situations where you need to increase specificity because you’re at war with some styles you don’t control.

Separator

The separator option lets you customize which character should be used to separate modifiers (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.

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 safelist 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: [
    'margin',
    'padding',
    'backgroundColor',
    // ...
  ]
}

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
accentColor The accent-color utilities like accent-green-800
accessibility The sr-only and not-sr-only utilities
alignContent The align-content utilities like content-between
alignItems The align-items utilities like items-center
alignSelf The align-self utilities like self-end
animation The animation utilities like animate-ping
appearance The appearance utilities like appearance-none
aspectRatio The aspect-ratio utilities like aspect-square
backdropBlur The backdrop-blur utilities like backdrop-blur-md
backdropBrightness The backdrop-brightness utilities like backdrop-brightness-100
backdropContrast The backdrop-contrast utilities like backdrop-contrast-100
backdropFilter The backdrop-filter utilities like backdrop-filter
backdropGrayscale The backdrop-grayscale utilities like backdrop-grayscale-0
backdropHueRotate The backdrop-hue-rotate utilities like backdrop-hue-rotate-30
backdropInvert The backdrop-invert utilities like backdrop-invert-0
backdropOpacity The backdrop-opacity utilities like backdrop-opacity-50
backdropSaturate The backdrop-saturate utilities like backdrop-saturate-100
backdropSepia The backdrop-sepia utilities like backdrop-sepia-0
backgroundAttachment The background-attachment utilities like bg-local
backgroundBlendMode The background-blend-mode utilities like bg-blend-color-burn
backgroundClip The background-clip utilities like bg-clip-padding
backgroundColor The background-color utilities like bg-green-800
backgroundImage The background-image utilities like bg-gradient-to-br
backgroundOpacity The background-color opacity utilities like bg-opacity-25
backgroundOrigin The background-origin utilities like bg-origin-padding
backgroundPosition The background-position utilities like bg-left-top
backgroundRepeat The background-repeat utilities like bg-repeat-x
backgroundSize The background-size utilities like bg-cover
blur The blur utilities like blur-md
borderCollapse The border-collapse utilities like border-collapse
borderColor The border-color utilities like border-e-green-800
borderOpacity The border-color opacity utilities like border-opacity-25
borderRadius The border-radius utilities like rounded-ss-lg
borderSpacing The border-spacing utilities like border-spacing-x-28
borderStyle The border-style utilities like border-dotted
borderWidth The border-width utilities like border-e-4
boxDecorationBreak The box-decoration-break utilities like decoration-clone
boxShadow The box-shadow utilities like shadow-lg
boxShadowColor The box-shadow-color utilities like shadow-green-800
boxSizing The box-sizing utilities like box-border
breakAfter The break-after utilities like break-after-avoid-page
breakBefore The break-before utilities like break-before-avoid-page
breakInside The break-inside utilities like break-inside-avoid
brightness The brightness utilities like brightness-100
captionSide The caption-side utilities like caption-top
caretColor The caret-color utilities like caret-green-800
clear The clear utilities like clear-right
columns The columns utilities like columns-auto
container The container component
content The content utilities like content-none
contrast The contrast utilities like contrast-100
cursor The cursor utilities like cursor-grab
display The display utilities like table-column-group
divideColor The between elements border-color utilities like divide-slate-500
divideOpacity The divide-opacity utilities like divide-opacity-50
divideStyle The divide-style utilities like divide-dotted
divideWidth The between elements border-width utilities like divide-x-2
dropShadow The drop-shadow utilities like drop-shadow-lg
fill The fill utilities like fill-green-700
filter The filter utilities like filter
flex The flex utilities like flex-auto
flexBasis The flex-basis utilities like basis-px
flexDirection The flex-direction utilities like flex-row-reverse
flexGrow The flex-grow utilities like flex-grow
flexShrink The flex-shrink utilities like flex-shrink
flexWrap The flex-wrap utilities like flex-wrap-reverse
float The float utilities like float-left
fontFamily The font-family utilities like font-serif
fontSize The font-size utilities like text-3xl
fontSmoothing The font-smoothing utilities like antialiased
fontStyle The font-style utilities like italic
fontVariantNumeric The font-variant-numeric utilities like oldstyle-nums
fontWeight The font-weight utilities like font-medium
gap The gap utilities like gap-x-28
gradientColorStops The gradient-color-stops utilities like via-emerald-700
grayscale The grayscale utilities like grayscale-0
gridAutoColumns The grid-auto-columns utilities like auto-cols-min
gridAutoFlow The grid-auto-flow utilities like grid-flow-dense
gridAutoRows The grid-auto-rows utilities like auto-rows-min
gridColumn The grid-column utilities like col-span-6
gridColumnEnd The grid-column-end utilities like col-end-7
gridColumnStart The grid-column-start utilities like col-start-7
gridRow The grid-row utilities like row-span-3
gridRowEnd The grid-row-end utilities like row-end-4
gridRowStart The grid-row-start utilities like row-start-4
gridTemplateColumns The grid-template-columns utilities like grid-cols-7
gridTemplateRows The grid-template-rows utilities like grid-rows-4
height The height utilities like h-72
hueRotate The hue-rotate utilities like hue-rotate-30
hyphens The hyphens utilities like hyphens-manual
inset The inset utilities like end-44
invert The invert utilities like invert-0
isolation The isolation utilities like isolate
justifyContent The justify-content utilities like justify-center
justifyItems The justify-items utilities like justify-items-end
justifySelf The justify-self utilities like justify-self-end
letterSpacing The letter-spacing utilities like tracking-normal
lineClamp The line-clamp utilities like line-clamp-4
lineHeight The line-height utilities like leading-9
listStyleImage The list-style-image utilities like list-image-none
listStylePosition The list-style-position utilities like list-inside
listStyleType The list-style-type utilities like list-disc
margin The margin utilities like me-28
maxHeight The max-height utilities like max-h-40
maxWidth The max-width utilities like max-w-6xl
minHeight The min-height utilities like min-h-screen
minWidth The min-width utilities like min-w-min
mixBlendMode The mix-blend-mode utilities like mix-blend-hard-light
objectFit The object-fit utilities like object-fill
objectPosition The object-position utilities like object-left-top
opacity The opacity utilities like opacity-50
order The order utilities like order-8
outlineColor The outline-color utilities like outline-green-800
outlineOffset The outline-offset utilities like outline-offset-2
outlineStyle The outline-style utilities like outline-dashed
outlineWidth The outline-width utilities like outline-2
overflow The overflow utilities like overflow-x-hidden
overscrollBehavior The overscroll-behavior utilities like overscroll-y-contain
padding The padding utilities like pe-28
placeContent The place-content utilities like place-content-between
placeItems The place-items utilities like place-items-center
placeSelf The place-self utilities like place-self-end
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
preflight Tailwind's base/reset styles
resize The resize utilities like resize-y
ringColor The ring-color utilities like ring-green-800
ringOffsetColor The ring-offset-color utilities like ring-offset-green-800
ringOffsetWidth The ring-offset-width utilities like ring-offset-2
ringOpacity The ring-opacity utilities like ring-opacity-50
ringWidth The ring-width utilities like ring-4
rotate The rotate utilities like rotate-6
saturate The saturate utilities like saturate-100
scale The scale utilities like scale-x-95
scrollBehavior The scroll-behavior utilities like scroll-auto
scrollMargin The scroll-margin utilities like scroll-me-28
scrollPadding The scroll-padding utilities like scroll-pe-28
scrollSnapAlign The scroll-snap-align utilities like snap-end
scrollSnapStop The scroll-snap-stop utilities like snap-normal
scrollSnapType The scroll-snap-type utilities like snap-y
sepia The sepia utilities like sepia-0
skew The skew utilities like skew-x-12
space The "space-between" utilities like space-x-4
stroke The stroke utilities like stroke-green-700
strokeWidth The stroke-width utilities like stroke-1
tableLayout The table-layout utilities like table-auto
textAlign The text-align utilities like text-right
textColor The text-color utilities like text-green-800
textDecoration The text-decoration utilities like overline
textDecorationColor The text-decoration-color utilities like decoration-green-800
textDecorationStyle The text-decoration-style utilities like decoration-dotted
textDecorationThickness The text-decoration-thickness utilities like decoration-4
textIndent The text-indent utilities like indent-28
textOpacity The text-opacity utilities like text-opacity-50
textOverflow The text-overflow utilities like overflow-ellipsis
textTransform The text-transform utilities like lowercase
textUnderlineOffset The text-underline-offset utilities like underline-offset-2
touchAction The touch-action utilities like touch-pan-right
transform The transform utility (for enabling transform features)
transformOrigin The transform-origin utilities like origin-bottom-right
transitionDelay The transition-delay utilities like delay-200
transitionDuration The transition-duration utilities like duration-200
transitionProperty The transition-property utilities like transition-colors
transitionTimingFunction The transition-timing-function utilities like ease-in
translate The translate utilities like translate-x-full
userSelect The user-select utilities like select-text
verticalAlign The vertical-align utilities like align-bottom
visibility The visibility utilities like invisible
whitespace The whitespace utilities like whitespace-pre
width The width utilities like w-1.5
willChange The will-change utilities like will-change-scroll
wordBreak The word-break utilities like break-words
zIndex The z-index utilities like z-30

Using multiple configurations

For projects that need to generate multiple CSS files using different Tailwind configurations, use the @config directive to specify which config file should be used for each CSS entry point:

Learn more about the @config directive in the Functions & Directives documentation.

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)

fullConfig.theme.width[4]
// => '1rem'

fullConfig.theme.screens.md
// => '768px'

fullConfig.theme.boxShadow['2xl']
// => '0 25px 50px -12px rgba(0, 0, 0, 0.25)'

Note that this will transitively pull in a lot of our build-time dependencies, resulting in bigger client-side bundle size. To avoid this, we recommend using a tool like babel-plugin-preval to generate a static version of your configuration at build-time.

TypeScript types

We ship first-party TypeScript types for the tailwind.config.js file which give you all sorts of useful IDE support, and makes it a lot easier to make changes to your configuration without referencing the documentation quite as much.

Configuration files generated with Tailwind CLI include the necessary type annotation by default, but to configure TypeScript types manually, just add the type annotation above your configuration object:

tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

© 2022 Tailwind Labs Inc.
https://tailwindcss.com/docs/configuration