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
const colors = require('tailwindcss/colors')
module.exports = {
theme: {
colors: {
gray: colors.coolGray,
blue: colors.lightBlue,
red: colors.rose,
pink: colors.fuchsia,
},
fontFamily: {
sans: ['Graphik', 'sans-serif'],
serif: ['Merriweather', 'serif'],
},
extend: {
spacing: {
'128': '32rem',
'144': '36rem',
},
borderRadius: {
'4xl': '2rem',
}
}
},
variants: {
extend: {
borderColor: ['focus-visible'],
opacity: ['disabled'],
}
}
}
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.
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 = {
purge: [],
darkMode: false, // or 'media' or 'class'
theme: {
extend: {},
},
variants: {
extend: {},
},
plugins: [],
}
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: [
tailwindcss: { config: './tailwindcss-config.js' },
],
}
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:
module.exports = {
plugins: {
tailwindcss: {},
autoprefixer: {},
},
}
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, fonts, type scale, border sizes, breakpoints — anything related to the visual design of your site.
// tailwind.config.js
module.exports = {
theme: {
colors: {
gray: colors.coolGray,
blue: colors.lightBlue,
red: colors.rose,
pink: colors.fuchsia,
},
fontFamily: {
sans: ['Graphik', 'sans-serif'],
serif: ['Merriweather', 'serif'],
},
extend: {
spacing: {
'128': '32rem',
'144': '36rem',
},
borderRadius: {
'4xl': '2rem',
}
}
}
}
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: {
fill: [],
extend: {
borderColor: ['focus-visible'],
opacity: ['disabled'],
}
},
}
Learn more in the variants configuration guide.
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.
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.
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 prefixes. 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">
<!-- -->
</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 responsive utility like this:
@variants hover {
.bg-brand-gradient { /* ... */ }
}
...the generated responsive classes 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:
@variants hover {
.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
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>
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: '_',
}
If you are using the extend
feature to enable extra variants, those variants are automatically sorted to respect a sensible default variant order.
You can customize this if necessary under the variantOrder
key:
// tailwind.config.js
module.exports = {
// ...
variantOrder: [
'first',
'last',
'odd',
'even',
'visited',
'checked',
'group-hover',
'group-focus',
'focus-within',
'hover',
'focus',
'focus-visible',
'active',
'disabled',
]
}
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 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 |
---|---|
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-end |
alignItems | The align-items utilities like items-center |
alignSelf | The align-self utilities like self-end |
animation | The animation utilities like animate-none |
appearance | The appearance utilities like appearance-none |
backgroundAttachment | The background-attachment utilities like bg-local |
backgroundClip | The background-clip utilities like bg-clip-padding |
backgroundColor | The background-color utilities like bg-green-700 |
backgroundImage | The background-image utilities like bg-gradient-to-br |
backgroundOpacity | The background-color opacity utilities like bg-opacity-25 |
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 |
borderCollapse | The border-collapse utilities like border-collapse |
borderColor | The border-color utilities like border-green-700 |
borderOpacity | The border-color opacity utilities like border-opacity-25 |
borderRadius | The border-radius utilities like rounded-l-3xl |
borderStyle | The border-style utilities like border-dotted |
borderWidth | The border-width utilities like border-l-2 |
boxShadow | The box-shadow utilities like shadow-lg |
boxSizing | The box-sizing utilities like box-border |
clear | The clear utilities like clear-right |
cursor | The cursor utilities like cursor-wait |
display | The display utilities like table-column-group |
divideColor | The between elements border-color utilities like divide-gray-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 |
fill | The fill utilities like fill-current |
flex | The flex utilities like flex-auto |
flexDirection | The flex-direction utilities like flex-row-reverse |
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-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 lining-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-green-700 |
gridAutoColumns | The grid-auto-columns utilities like auto-cols-min |
gridAutoFlow | The grid-auto-flow utilities like grid-flow-col |
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-64 |
inset | The inset utilities like bottom-10 |
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 |
lineHeight | The line-height utilities like leading-9 |
listStylePosition | The list-style-position utilities like list-inside |
listStyleType | The list-style-type utilities like list-disc |
margin | The margin utilities like ml-8 |
maxHeight | The max-height utilities like max-h-32 |
maxWidth | The max-width utilities like max-w-5xl |
minHeight | The min-height utilities like min-h-full |
minWidth | The min-width utilities like min-w-full |
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 |
outline | The outline utilities like outline-white |
overflow | The overflow utilities like overflow-y-auto |
overscrollBehavior | The overscroll-behavior utilities like overscroll-y-contain |
padding | The padding utilities like pr-4 |
placeContent | The place-content utilities like place-content-between |
placeholderColor | The placeholder color utilities like placeholder-red-600 |
placeholderOpacity | The placeholder color opacity utilities like placeholder-opacity-25 |
placeItems | The place-items utilities like place-items-end |
placeSelf | The place-self utilities like place-self-end |
pointerEvents | The pointer-events utilities like pointer-events-none |
position | The position utilities like absolute |
resize | The resize utilities like resize-y |
ringColor | The ring-color utilities like ring-green-700 |
ringOffsetColor | The ring-offset-color utilities like ring-offset-green-700 |
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-2 |
rotate | The rotate utilities like rotate-180 |
scale | The scale utilities like scale-x-95 |
skew | The skew utilities like -skew-x-1 |
space | The "space-between" utilities like space-x-4 |
stroke | The stroke utilities like stroke-current |
strokeWidth | The stroke-width utilities like stroke-1 |
tableLayout | The table-layout utilities like table-auto |
textAlign | The text-align utilities like text-center |
textColor | The text-color utilities like text-green-700 |
textDecoration | The text-decoration utilities like line-through |
textOpacity | The text-opacity utilities like text-opacity-50 |
textOverflow | The text-overflow utilities like overflow-ellipsis |
textTransform | The text-transform utilities like lowercase |
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-middle |
visibility | The visibility utilities like visible |
whitespace | The whitespace utilities like whitespace-pre |
width | The width utilities like w-0.5 |
wordBreak | The word-break utilities like break-words |
zIndex | The z-index utilities like z-30 |
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 bundle client-size size. To avoid this, we recommend using a tool like babel-plugin-preval to generate a static version of your configuration at build-time.