Customizing and Configuration File Basics

Reasons for customizing Tailwind

Tailwind is an engine that generates a lot of CSS classes, and this engine has a lot of hooks that allow us to alter the set of utilities available to us.

We might want to customize Tailwind for several reasons:

• Change defaults: Tailwind provides default step values for most of its utilities—for example, the common steps for margins, padding, and other spacing items. It has default screen sizes for responsive breakpoints. Tailwind also provides a default set of colors, but we may want to add our own. In the configuration file, we can change these.

• Change the set of classes: Tailwind generates a lot of CSS classes. For file size purposes, we might want to reduce that list— for example, if we know we are not using flexbox, we can tell Tailwind not to generate any flexbox-related utilities. Conversely, Tailwind offers about a dozen prefix modifiers that offer powerful behavior but are not generated by default.

• Add new behavior: Although we can write our own extensions in regular CSS, we can also add new items as plug-ins that are part of the Tailwind configuration. This makes it easier for them to share and integrate with other Tailwind behavior.

• Integrate with legacy CSS: We may want to start using Tailwind on a site that already has a lot of CSS. Tailwind provides configuration options that allow us to ensure that Tailwind utilities do not conflict with existing CSS or with the limitations of our HTML templating tool.

Let us look at how to customize Tailwind to our liking, starting with the configuration file.

Configuration file basics

The configuration file is optionally generated as part of our Tailwind installation. We can also create it at any time after we install the Tailwind npm package with the command, npx tailwindcss init. Below is how the minimal configuration file looks like:

module.exports = {
  future: {},
  purge: [],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

If we want a configuration file with the entire default configuration explicitly listed, we can get it with npx tailwindcss init --full. Most of what we are going to be looking at will go in the theme and variants sections.

Tailwind considers each family of utilities a core plugin; we can see a complete list in the Tailwind documentation. The theme object references these core plugin names to customize the core plugins. Most of the core plugins have customization options.

Change default values

In the configuration file, the theme object has keys that are the names of each core plug-in and values that are the configuration options for that plug-in. The three special configuration options—screen, color, and spacing—are not core plug-ins themselves but are the basis for the configuration of many other core plug-ins.

It’s worth mentioning here that Tailwind’s use of the word “theme” is different from how we might see it used in other places, where “theme” refers to a set of colors, as in dark theme versus light theme. For Tailwind, the theme is the entire set of defaults, and there is only one. If we want to change color schemes, we need to use CSS variables or thedark: prefix to specify behavior under dark mode.

Note: We can see the entire default theme on GitHub. This is the theme in the main branch of Tailwind, so it may be slightly ahead of the released version.

We can customize the theme in two ways:

1. Override entire options
2. Extend options

Override entire options

To override, we provide a new set of values for an entire object, either a core plugin or one of the special values in the theme object. This example changes the entire set of screen breakpoints. Overriding the theme object this way completely replaces the default values:

theme: {
    screens: {
      'phone': '640px',
      'landscape': '768px',
      'tablet': '1024px',
      'laptop': '1280px',
    } 
}

Extend options

If we want to preserve the existing default values but add new ones on top, we can use theme#extend. This configuration adds an extra, extra-wide screen breakpoint:

theme: {
  extend: {
    screens: {
      3xl: '2440px',
    } 
  }
}