Customization

Configuration

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.

tailwind.config.js

  1. module.exports = {
  2. content: ['./src/**/*.{html,js}'],
  3. theme: {
  4. colors: {
  5. 'blue': '#1fb6ff',
  6. 'purple': '#7e5bef',
  7. 'pink': '#ff49db',
  8. 'orange': '#ff7849',
  9. 'green': '#13ce66',
  10. 'yellow': '#ffc82c',
  11. 'gray-dark': '#273444',
  12. 'gray': '#8492a6',
  13. 'gray-light': '#d3dce6',
  14. },
  15. fontFamily: {
  16. sans: ['Graphik', 'sans-serif'],
  17. serif: ['Merriweather', 'serif'],
  18. },
  19. extend: {
  20. spacing: {
  21. '8xl': '96rem',
  22. '9xl': '128rem',
  23. },
  24. borderRadius: {
  25. '4xl': '2rem',
  26. }
  27. }
  28. },
  29. }

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:

  1. npx tailwindcss init

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

tailwind.config.js

  1. module.exports = {
  2. content: [],
  3. theme: {
  4. extend: {},
  5. },
  6. plugins: [],
  7. }

Using a different file name

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

  1. 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:

  1. 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

  1. module.exports = {
  2. plugins: {
  3. tailwindcss: { config: './tailwindcss-config.js' },
  4. },
  5. }

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:

  1. npx tailwindcss init -p

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

postcss.config.js

  1. module.exports = {
  2. plugins: {
  3. tailwindcss: {},
  4. autoprefixer: {},
  5. },
  6. }

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:

  1. 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

  1. module.exports = {
  2. content: [
  3. './pages/**/*.{html,js}',
  4. './components/**/*.{html,js}',
  5. ],
  6. // ...
  7. }

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

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

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

  1. module.exports = {
  2. // ...
  3. plugins: [
  4. require('@tailwindcss/forms'),
  5. require('@tailwindcss/aspect-ratio'),
  6. require('@tailwindcss/typography'),
  7. require('tailwindcss-children'),
  8. ],
  9. }

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

  1. module.exports = {
  2. // ...
  3. presets: [
  4. require('@acmecorp/base-tailwind-config')
  5. ],
  6. // Project-specific customizations
  7. theme: {
  8. //...
  9. },
  10. }

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

  1. module.exports = {
  2. prefix: 'tw-',
  3. }

Now every class will be generated with the configured prefix:

  1. .tw-text-left {
  2. text-align: left;
  3. }
  4. .tw-text-center {
  5. text-align: center;
  6. }
  7. .tw-text-right {
  8. text-align: right;
  9. }
  10. /* 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:

  1. <div class="tw-text-lg md:tw-text-xl tw-bg-red-500 hover:tw-bg-blue-500">
  2. <!-- -->
  3. </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:

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

…the generated variants will not have your configured prefix:

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

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

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

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

  1. module.exports = {
  2. important: true,
  3. }

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

  1. .leading-none {
  2. line-height: 1 !important;
  3. }
  4. .leading-tight {
  5. line-height: 1.25 !important;
  6. }
  7. .leading-snug {
  8. line-height: 1.375 !important;
  9. }
  10. /* 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:

  1. @layer utilities {
  2. .bg-brand-gradient {
  3. background-image: linear-gradient(#3490dc, #6574cd) !important;
  4. }
  5. }

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

  1. module.exports = {
  2. // ...
  3. important: '#app',
  4. }

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:

  1. <html>
  2. <!-- ... -->
  3. <style>
  4. .high-specificity .nested .selector {
  5. color: blue;
  6. }
  7. </style>
  8. <body id="app">
  9. <div class="high-specificity">
  10. <div class="nested">
  11. <!-- Will be red-500 -->
  12. <div class="selector text-red-500"><!-- ... --></div>
  13. </div>
  14. </div>
  15. <!-- Will be #bada55 -->
  16. <div class="text-red-500" style="color: #bada55;"><!-- ... --></div>
  17. </body>
  18. </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.

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

  1. module.exports = {
  2. separator: '_',
  3. }

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

  1. module.exports = {
  2. corePlugins: {
  3. float: false,
  4. objectFit: false,
  5. objectPosition: false,
  6. }
  7. }

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

  1. module.exports = {
  2. corePlugins: [
  3. 'margin',
  4. 'padding',
  5. 'backgroundColor',
  6. // ...
  7. ]
  8. }

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

  1. module.exports = {
  2. corePlugins: []
  3. }

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

Core PluginDescription
accentColorThe accent-color utilities like accent-green-700
accessibilityThe sr-only and not-sr-only utilities
alignContentThe align-content utilities like content-end
alignItemsThe align-items utilities like items-center
alignSelfThe align-self utilities like self-end
animationThe animation utilities like animate-ping
appearanceThe appearance utilities like appearance-none
aspectRatioThe aspect-ratio utilities like aspect-square
backdropBlurThe backdrop-blur utilities like backdrop-blur-md
backdropBrightnessThe backdrop-brightness utilities like backdrop-brightness-100
backdropContrastThe backdrop-contrast utilities like backdrop-contrast-100
backdropFilterThe backdrop-filter utilities like backdrop-filter
backdropGrayscaleThe backdrop-grayscale utilities like backdrop-grayscale-0
backdropHueRotateThe backdrop-hue-rotate utilities like backdrop-hue-rotate-30
backdropInvertThe backdrop-invert utilities like backdrop-invert-0
backdropOpacityThe backdrop-opacity utilities like backdrop-opacity-50
backdropSaturateThe backdrop-saturate utilities like backdrop-saturate-100
backdropSepiaThe backdrop-sepia utilities like backdrop-sepia-0
backgroundAttachmentThe background-attachment utilities like bg-local
backgroundBlendModeThe background-blend-mode utilities like bg-blend-color-burn
backgroundClipThe background-clip utilities like bg-clip-padding
backgroundColorThe background-color utilities like bg-green-700
backgroundImageThe background-image utilities like bg-gradient-to-br
backgroundOpacityThe background-color opacity utilities like bg-opacity-25
backgroundOriginThe background-origin utilities like bg-origin-padding
backgroundPositionThe background-position utilities like bg-left-top
backgroundRepeatThe background-repeat utilities like bg-repeat-x
backgroundSizeThe background-size utilities like bg-cover
blurThe blur utilities like blur-md
borderCollapseThe border-collapse utilities like border-collapse
borderColorThe border-color utilities like border-t-green-700
borderOpacityThe border-color opacity utilities like border-opacity-25
borderRadiusThe border-radius utilities like rounded-l-lg
borderStyleThe border-style utilities like border-dotted
borderWidthThe border-width utilities like border-t-4
boxDecorationBreakThe box-decoration-break utilities like decoration-clone
boxShadowThe box-shadow utilities like shadow-lg
boxShadowColorThe box-shadow-color utilities like shadow-green-700
boxSizingThe box-sizing utilities like box-border
breakAfterThe break-after utilities like break-after-avoid-page
breakBeforeThe break-before utilities like break-before-avoid-page
breakInsideThe break-inside utilities like break-inside-avoid
brightnessThe brightness utilities like brightness-100
caretColorThe caret-color utilities like caret-green-700
clearThe clear utilities like clear-right
columnsThe columns utilities like columns-auto
containerThe container component
contentThe content utilities like content-none
contrastThe contrast utilities like contrast-100
cursorThe cursor utilities like cursor-grab
displayThe display utilities like table-column-group
divideColorThe between elements border-color utilities like divide-gray-500
divideOpacityThe divide-opacity utilities like divide-opacity-50
divideStyleThe divide-style utilities like divide-dotted
divideWidthThe between elements border-width utilities like divide-x-2
dropShadowThe drop-shadow utilities like drop-shadow-lg
fillThe fill utilities like fill-green-700
filterThe filter utilities like filter
flexThe flex utilities like flex-auto
flexBasisThe flex-basis utilities like basis-px
flexDirectionThe flex-direction utilities like flex-row-reverse
flexGrowThe flex-grow utilities like flex-grow
flexShrinkThe flex-shrink utilities like flex-shrink
flexWrapThe flex-wrap utilities like flex-wrap-reverse
floatThe float utilities like float-left
fontFamilyThe font-family utilities like font-serif
fontSizeThe font-size utilities like text-3xl
fontSmoothingThe font-smoothing utilities like antialiased
fontStyleThe font-style utilities like italic
fontVariantNumericThe font-variant-numeric utilities like lining-nums
fontWeightThe font-weight utilities like font-medium
gapThe gap utilities like gap-x-28
gradientColorStopsThe gradient-color-stops utilities like via-green-700
grayscaleThe grayscale utilities like grayscale-0
gridAutoColumnsThe grid-auto-columns utilities like auto-cols-min
gridAutoFlowThe grid-auto-flow utilities like grid-flow-col
gridAutoRowsThe grid-auto-rows utilities like auto-rows-min
gridColumnThe grid-column utilities like col-span-6
gridColumnEndThe grid-column-end utilities like col-end-7
gridColumnStartThe grid-column-start utilities like col-start-7
gridRowThe grid-row utilities like row-span-3
gridRowEndThe grid-row-end utilities like row-end-4
gridRowStartThe grid-row-start utilities like row-start-4
gridTemplateColumnsThe grid-template-columns utilities like grid-cols-7
gridTemplateRowsThe grid-template-rows utilities like grid-rows-4
heightThe height utilities like h-72
hueRotateThe hue-rotate utilities like hue-rotate-30
insetThe inset utilities like top-44
invertThe invert utilities like invert-0
isolationThe isolation utilities like isolate
justifyContentThe justify-content utilities like justify-center
justifyItemsThe justify-items utilities like justify-items-end
justifySelfThe justify-self utilities like justify-self-end
letterSpacingThe letter-spacing utilities like tracking-normal
lineHeightThe line-height utilities like leading-9
listStylePositionThe list-style-position utilities like list-inside
listStyleTypeThe list-style-type utilities like list-disc
marginThe margin utilities like mt-28
maxHeightThe max-height utilities like max-h-36
maxWidthThe max-width utilities like max-w-6xl
minHeightThe min-height utilities like min-h-screen
minWidthThe min-width utilities like min-w-min
mixBlendModeThe mix-blend-mode utilities like mix-blend-color-burn
objectFitThe object-fit utilities like object-fill
objectPositionThe object-position utilities like object-left-top
opacityThe opacity utilities like opacity-50
orderThe order utilities like order-8
outlineColorThe outline-color utilities like outline-green-700
outlineOffsetThe outline-offset utilities like outline-offset-2
outlineStyleThe outline-style utilities like outline-dashed
outlineWidthThe outline-width utilities like outline-2
overflowThe overflow utilities like overflow-x-hidden
overscrollBehaviorThe overscroll-behavior utilities like overscroll-y-contain
paddingThe padding utilities like pt-28
placeContentThe place-content utilities like place-content-between
placeItemsThe place-items utilities like place-items-end
placeSelfThe place-self utilities like place-self-end
placeholderColorThe placeholder color utilities like placeholder-red-600
placeholderOpacityThe placeholder color opacity utilities like placeholder-opacity-25
pointerEventsThe pointer-events utilities like pointer-events-none
positionThe position utilities like absolute
preflightTailwind’s base/reset styles
resizeThe resize utilities like resize-y
ringColorThe ring-color utilities like ring-green-700
ringOffsetColorThe ring-offset-color utilities like ring-offset-green-700
ringOffsetWidthThe ring-offset-width utilities like ring-offset-2
ringOpacityThe ring-opacity utilities like ring-opacity-50
ringWidthThe ring-width utilities like ring-4
rotateThe rotate utilities like rotate-6
saturateThe saturate utilities like saturate-100
scaleThe scale utilities like scale-x-95
scrollBehaviorThe scroll-behavior utilities like scroll-auto
scrollMarginThe scroll-margin utilities like scroll-mt-28
scrollPaddingThe scroll-padding utilities like scroll-pt-28
scrollSnapAlignThe scroll-snap-align utilities like snap-end
scrollSnapStopThe scroll-snap-stop utilities like snap-normal
scrollSnapTypeThe scroll-snap-type utilities like snap-y
sepiaThe sepia utilities like sepia-0
skewThe skew utilities like skew-x-12
spaceThe “space-between” utilities like space-x-4
strokeThe stroke utilities like stroke-green-700
strokeWidthThe stroke-width utilities like stroke-1
tableLayoutThe table-layout utilities like table-auto
textAlignThe text-align utilities like text-center
textColorThe text-color utilities like text-green-700
textDecorationThe text-decoration utilities like overline
textDecorationColorThe text-decoration-color utilities like decoration-green-700
textDecorationStyleThe text-decoration-style utilities like decoration-dotted
textDecorationThicknessThe text-decoration-thickness utilities like decoration-4
textIndentThe text-indent utilities like indent-28
textOpacityThe text-opacity utilities like text-opacity-50
textOverflowThe text-overflow utilities like overflow-ellipsis
textTransformThe text-transform utilities like lowercase
textUnderlineOffsetThe text-underline-offset utilities like underline-offset-2
touchActionThe touch-action utilities like touch-pan-right
transformThe transform utility (for enabling transform features)
transformOriginThe transform-origin utilities like origin-bottom-right
transitionDelayThe transition-delay utilities like delay-200
transitionDurationThe transition-duration utilities like duration-200
transitionPropertyThe transition-property utilities like transition-colors
transitionTimingFunctionThe transition-timing-function utilities like ease-in
translateThe translate utilities like translate-x-full
userSelectThe user-select utilities like select-text
verticalAlignThe vertical-align utilities like align-bottom
visibilityThe visibility utilities like visible
whitespaceThe whitespace utilities like whitespace-pre
widthThe width utilities like w-1.5
willChangeThe will-change utilities like will-change-scroll
wordBreakThe word-break utilities like break-words
zIndexThe z-index utilities like z-30

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:

  1. import resolveConfig from 'tailwindcss/resolveConfig'
  2. import tailwindConfig from './tailwind.config.js'
  3. const fullConfig = resolveConfig(tailwindConfig)
  4. fullConfig.theme.width[4]
  5. // => '1rem'
  6. fullConfig.theme.screens.md
  7. // => '768px'
  8. fullConfig.theme.boxShadow['2xl']
  9. // => '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-side size. To avoid this, we recommend using a tool like babel-plugin-preval to generate a static version of your configuration at build-time.