Customization
Customizing the default theme for your project.
The theme
section of your tailwind.config.js
file is where you define your project’s color palette, type scale, fonts, breakpoints, border radius values, and more.
module.exports = {
theme: {
screens: {
sm: '480px',
md: '768px',
lg: '976px',
xl: '1440px',
},
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: {
'128': '32rem',
'144': '36rem',
},
borderRadius: {
'4xl': '2rem',
}
}
}
}
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 it; you’re encouraged to customize it as much as you need to fit the goals of your design.
The theme
object contains keys for screens
, colors
, and spacing
, as well as a key for each customizable core plugin.
See the theme configuration reference or the default theme for a complete list of theme options.
The screens
key allows you to customize the responsive breakpoints in your project.
module.exports = {
theme: {
screens: {
'sm': '640px',
'md': '768px',
'lg': '1024px',
'xl': '1280px',
'2xl': '1536px',
}
}
}
To learn more, see the breakpoint customization documentation.
The colors
key allows you to customize the global color palette for your project.
module.exports = {
theme: {
colors: {
transparent: 'transparent',
black: '#000',
white: '#fff',
gray: {
100: '#f7fafc',
// ...
900: '#1a202c',
},
// ...
}
}
}
By default, these colors are inherited by all color-related core plugins, like backgroundColor
, borderColor
, textColor
, and others.
To learn more, see the color customization documentation.
The spacing
key allows you to customize the global spacing and sizing scale for your project.
module.exports = {
theme: {
spacing: {
px: '1px',
0: '0',
0.5: '0.125rem',
1: '0.25rem',
1.5: '0.375rem',
2: '0.5rem',
2.5: '0.625rem',
3: '0.75rem',
3.5: '0.875rem',
4: '1rem',
5: '1.25rem',
6: '1.5rem',
7: '1.75rem',
8: '2rem',
9: '2.25rem',
10: '2.5rem',
11: '2.75rem',
12: '3rem',
14: '3.5rem',
16: '4rem',
20: '5rem',
24: '6rem',
28: '7rem',
32: '8rem',
36: '9rem',
40: '10rem',
44: '11rem',
48: '12rem',
52: '13rem',
56: '14rem',
60: '15rem',
64: '16rem',
72: '18rem',
80: '20rem',
96: '24rem',
},
}
}
By default, these values are inherited by the padding
, margin
, width
, height
, maxHeight
, flex-basis
, gap
, inset
, space
, translate
, scrollMargin
, scrollPadding
, and textIndent
core plugins.
To learn more, see the spacing customization documentation.
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:
.rounded-none { border-radius: 0 }
.rounded-sm { border-radius: .125rem }
.rounded { border-radius: .25rem }
.rounded-lg { border-radius: .5rem }
.rounded-full { border-radius: 9999px }
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 and is supported by all core plugins.
To learn more about customizing a specific core plugin, visit the documentation for that plugin.
For a complete reference of available theme properties and their default values, see the default theme configuration.
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.
If you’d like to preserve the default values for a theme option but also add new values, add your extensions under the extend
key in the theme
section of your configuration file.
For example, if you wanted to add an extra breakpoint but preserve the existing ones, you could extend the screens
property:
module.exports = {
theme: {
extend: {
// Adds a new breakpoint in addition to the default breakpoints
screens: {
'3xl': '1600px',
}
}
}
}
To override an option in the default theme, add your overrides directly under the theme
section of your 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.
You can of course both override some parts of the default theme and extend other parts of the default theme within the same configuration:
module.exports = {
theme: {
opacity: {
'0': '0',
'20': '0.2',
'40': '0.4',
'60': '0.6',
'80': '0.8',
'100': '1',
},
extend: {
screens: {
'3xl': '1600px',
}
}
}
}
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 an object that includes a theme()
function that you can use to look up other values in your theme using dot notation.
For example, you could generate background-size
utilities for every value in your spacing scale by referencing theme('spacing')
in your backgroundSize
configuration:
module.exports = {
theme: {
spacing: {
// ...
},
backgroundSize: ({ theme }) => ({
auto: 'auto',
cover: 'cover',
contain: 'contain',
...theme('spacing')
})
}
}
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.
Note that you can only use this kind of closure with top-level theme keys, not the keys inside of each section.
You can't use functions for individual values
module.exports = {
theme: {
fill: {
gray: ({ theme }) => theme('colors.gray')
}
}
}
Use functions for top-level theme keys
module.exports = {
theme: {
fill: ({ theme }) => ({
gray: theme('colors.gray')
})
}
}
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:
const defaultTheme = require('tailwindcss/defaultTheme')
module.exports = {
theme: {
extend: {
fontFamily: {
sans: [
'Lato',
...defaultTheme.fontFamily.sans,
]
}
}
}
}
If you don’t want to generate any classes for a certain core plugin, it’s better to set that plugin to false in your corePlugins
configuration than to provide an empty object for that key in your theme
configuration.
Don't assign an empty object in your theme configuration
module.exports = {
theme: {
opacity: {},
}
}
Do disable the plugin in your corePlugins configuration
module.exports = {
corePlugins: {
opacity: false,
}
}
The end result is the same, but since many core plugins expose no configuration they can only be disabled using corePlugins
anyways, so it’s better to be consistent.
Except for screens
, colors
, and spacing
, all of the keys in the theme
object map to one of Tailwind’s core plugins. Since many plugins are responsible for CSS properties that only accept a static set of values (like float
for example), note that not every plugin has a corresponding key in the theme
object.
All of these keys are also available under the theme.extend
key to enable extending the default theme.
Key | Description |
---|---|
screens | Your project's responsive breakpoints |
supports | Values for the supports property |
colors | Your project's color palette |
columns | Values for the columns property |
spacing | Your project's spacing scale |
animation | Values for the animation property |
aria | Values for the aria property |
aspectRatio | Values for the aspect-ratio property |
backdropBlur | Values for the backdropBlur plugin |
backdropBrightness | Values for the backdropBrightness plugin |
backdropContrast | Values for the backdropContrast plugin |
backdropGrayscale | Values for the backdropGrayscale plugin |
backdropHueRotate | Values for the backdropHueRotate plugin |
backdropInvert | Values for the backdropInvert plugin |
backdropOpacity | Values for the backdropOpacity plugin |
backdropSaturate | Values for the backdropSaturate plugin |
backdropSepia | Values for the backdropSepia plugin |
backgroundColor | Values for the background-color property |
backgroundImage | Values for the background-image property |
backgroundOpacity | Values for the background-opacity property |
backgroundPosition | Values for the background-position property |
backgroundSize | Values for the background-size property |
blur | Values for the blur plugin |
brightness | Values for the brightness plugin |
borderColor | Values for the border-color property |
borderOpacity | Values for the borderOpacity plugin |
borderRadius | Values for the border-radius property |
borderSpacing | Values for the border-spacing property |
borderWidth | Values for the borderWidth plugin |
boxShadow | Values for the box-shadow property |
boxShadowColor | Values for the boxShadowColor plugin |
caretColor | Values for the caret-color property |
accentColor | Values for the accent-color property |
contrast | Values for the contrast plugin |
container | Configuration for the container plugin |
content | Values for the content property |
cursor | Values for the cursor property |
divideColor | Values for the divideColor plugin |
divideOpacity | Values for the divideOpacity plugin |
divideWidth | Values for the divideWidth plugin |
dropShadow | Values for the dropShadow plugin |
fill | Values for the fill plugin |
grayscale | Values for the grayscale plugin |
hueRotate | Values for the hueRotate plugin |
invert | Values for the invert plugin |
flex | Values for the flex property |
flexBasis | Values for the flex-basis 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 |
gap | Values for the gap property |
gradientColorStops | Values for the gradientColorStops plugin |
gridAutoColumns | Values for the grid-auto-columns property |
gridAutoRows | Values for the grid-auto-rows property |
gridColumn | Values for the grid-column property |
gridColumnEnd | Values for the grid-column-end property |
gridColumnStart | Values for the grid-column-start property |
gridRow | Values for the grid-row property |
gridRowStart | Values for the grid-row-start property |
gridRowEnd | Values for the grid-row-end property |
gridTemplateColumns | Values for the grid-template-columns property |
gridTemplateRows | Values for the grid-template-rows property |
height | Values for the height property |
inset | Values for the top , right , bottom , and left properties |
keyframes | Keyframe values used in the animation plugin |
letterSpacing | Values for the letter-spacing property |
lineHeight | Values for the line-height property |
listStyleType | Values for the list-style-type 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 |
objectPosition | Values for the object-position property |
opacity | Values for the opacity property |
order | Values for the order property |
padding | Values for the padding property |
placeholderColor | Values for the placeholderColor plugin |
placeholderOpacity | Values for the placeholderOpacity plugin |
outlineColor | Values for the outline-color property |
outlineOffset | Values for the outline-offset property |
outlineWidth | Values for the outline-width property |
ringColor | Values for the ringColor plugin |
ringOffsetColor | Values for the ringOffsetColor plugin |
ringOffsetWidth | Values for the ringOffsetWidth plugin |
ringOpacity | Values for the ringOpacity plugin |
ringWidth | Values for the ringWidth plugin |
rotate | Values for the rotate plugin |
saturate | Values for the saturate plugin |
scale | Values for the scale plugin |
scrollMargin | Values for the scroll-margin property |
scrollPadding | Values for the scroll-padding property |
sepia | Values for the sepia plugin |
skew | Values for the skew plugin |
space | Values for the space plugin |
stroke | Values for the stroke property |
strokeWidth | Values for the stroke-width property |
textColor | Values for the text-color property |
textDecorationColor | Values for the text-decoration-color property |
textDecorationThickness | Values for the text-decoration-thickness property |
textUnderlineOffset | Values for the text-underline-offset property |
textIndent | Values for the text-indent property |
textOpacity | Values for the textOpacity plugin |
transformOrigin | Values for the transform-origin property |
transitionDelay | Values for the transition-delay property |
transitionDuration | Values for the transition-duration property |
transitionProperty | Values for the transition-property property |
transitionTimingFunction | Values for the transition-timing-function property |
translate | Values for the translate plugin |
width | Values for the width property |
willChange | Values for the will-change property |
zIndex | Values for the z-index property |