Overview

Tailwind is a CSS utility framework. It provides a large number of pre-built CSS classes that often only set a single CSS property. These can be used as values of the class attribute on HTML elements. They can also be customized in each application that uses them.

Other CSS frameworks such as Bootstrap, Bulma, Foundation, and Materialize define styling for components. Tailwind takes a different approach, providing lower level styling that can be combined in order to create custom looks.

Tailwind is not a replacement for CSS. It is still necessary for developers to be familiar with CSS properties and their supported values.

Tailwind is implemented as a PostCSS plugin. It can be used in conjunction with other PostCSS plugins such as those that support preprocessors like Sass.

The base styles in Tailwind provide a CSS reset known as "Preflight".

Pros

• Collocates markdown and styling
  Placing styles with the elements they affect makes it easier to visualize the result while looking at the HTML.

• Less naming required
  Tailwind enables styling HTML elements without giving them an id attribute or CSS class name. Using custom CSS classes requires assigning a name and associating that name with elements using the class attribute. Understanding the styling that a CSS class applies requires looking up the CSS class, often in another source file. Another option is to specify CSS properties using the style attribute, but using Tailwind CSS classes is more concise.

• More concise
  Most Tailwind CSS classes define a single CSS property. For example, the CSS property flex-direction: column; can be replaced by the Tailwind class flex-col.

• Removes need to think about specificity
  Specificity is the technique used in CSS to determine which CSS class should be applied to an element when multiple classes can apply. Because Tailwind directly associates CSS classes with HTML elements, those classes are always used regardless of the specificity of other rules.

• Easier responsive UIs
  Tailwind enables creating responsive UIs without writing media queries. This is done by prefixing Tailwind class names with a breakpoint name followed by a colon. For example: md:flex-col changes the flex-direction to column when the screen width is at or above the medium breakpoint.

• Configurable
  Tailwind is highly configurable. Default values can be overridden in a tailwind.config.js file.

• Supported by tools
  There are good, Tailwind-aware extensions for many editors including VS Code, Sublime Text, Vim, and Atom.

Cons

• Feels like giving up CSS emphasizes defining classes that describe sets of CSS properties that can be applied to multiple HTML elements. Thought goes into identifying well-named, cohesive sets of these properties. Using Tailwind feels like giving up on trying to do this. It encourages treating every HTML element as a one-off, just applying the styling that each element needs.

• Learning curve
  CSS has a steep learning curve. Tailwind adds to that. Effective use of Tailwind requires good knowledge of CSS. Developers that are not strong in CSS will struggle with using Tailwind.

• Clutter
  HTML becomes more cluttered when many elements have a class attribute with a long value. This makes it more difficult to understand the nested structure of the elements at a glance. The VS Code extension "Tailwind Fold" addresses this by automatically folding long class attribute values (and className property values in React).

• Inability to override
  When Tailwind classes are used in components of frameworks (ex. React, Vue, Svelte, and Angular), parent components cannot override their styling. For this reason it may be advisable to primarily use Tailwind for element layout and not for properties more likely to be overridden such as fonts and colors.

No Build Process

There are two approaches for using Tailwind without a build process.

The easiest approach is to include it from a CDN with this link tag:

<script src="https://cdn.tailwindcss.com"></script>

This has the downside that it includes every Tailwind CSS class, not just the ones actually used in the app.

A more involved approach is to generate a CSS file that only contains the Tailwind CSS classes that are actually used. The steps to do this are as follows:

1. Install Tailwind by entering npm install -D tailwindcss

2. Create the file tailwind.config.js by entering npx tailwindcss init

3. Edit the value of content in tailwind.config.js to specify the files that might used Tailwind classes. For example:

   content: ["**/*.{html,tsx}"],
   

4. Create the file global.css containing the following:

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

   This file can also define custom CSS classes.

5. Generate a CSS file containing only the Tailwind classes used in your app.

   Enter npx tailwindcss -i ./global.css -o public/tailwind.css --watch to generate public/tailwind.css now and again every time any of the "content" files are modified.

   Consider adding a package.json script for this such as:

   "tw": "npx tailwindcss -i ./global.css -o public/tailwind.css --watch"
   

6. Include the following link element in the base HTML of the app.

   <link href="/public/tailwind.css" rel="stylesheet" />
   

This also requires enabling serving static files with the following steps:

1. Install a plugin by entering bun add @elysiajs/static
2. In the server code, add a call to app.use(staticPlugin());

Basic Build Process

To install Tailwind in a project that has a package.json file, enter npm install -D tailwindcss.

A build process is required to use Tailwind. Many approaches can be taken, but the simplest is to create a public directory and add the following to the scripts section in the package.json file:

  "build:css": "tailwind build src/style.css -o public/style.css",

The file src/style.css should, at a minimum, contain the following:

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

To build the required set of Tailwind CSS classes in public/style.css, enter npm run build:css. This will replace @tailwind directives above with generated CSS. The generated CSS file will contain:

• normalize.css CSS rules
• Tailwind Preflight CSS rules
• all Tailwind utility class definitions in the categories referenced by the @tailwind directives in src/style.css

Highlights of the Preflight styles include:

• Default margins are removed from headings, paragraphs, and more.
• Headings become unstyled, so they have the same font-size and font-weight as normal text.
• Lists become unstyled, so they have no bullets, numbers, margins, or padding.
• Images become block-level instead of inline.
• Borders become solid 1px using the default border color of the current theme.
• Preflight styles can be overridden by defining CSS classes after @tailwind base;.

It is only necessary to rebuild the Tailwind-generated CSS when Tailwind directives have been modified or when the build process is configured to purge unused CSS rules and the Tailwind CSS classes being used have changed. Avoiding rebuilds speeds development.

For details on configuring various build tools to support Tailwind, see Tailwind installation.

PostCSS Build Process

An advantage of using PostCSS to build the Tailwind CSS used by an application is that other PostCSS plugins can also be used.

Building with PostCSS is only slightly more complicated. The steps to do this are:

1. Install all the PostCSS plugins to be used. For example:

   npm install -D postcss-cli autoprefixer@9.8.6
   

2. Create the file postcss.config.js containing:

   module.exports = {
     // Include a require for each PostCSS plugin to be used here.
     plugins: [require('tailwindcss'), require('autoprefixer')]
   };
   

3. Change the build:css script in package.json to:

   "build:css": "postcss src/style.css -o public/style.css"
   

Watching For Changes

To automatically run the build:css script any time a file in the src directory changes:

1. Enter npm install -D watch

2. Add the following script in package.json:

   "watch": "watch 'npm run build:css' ./src"
   

Configuration

To see all the Tailwind properties that can be customized, create a new configuration file by entering npx tailwindcss init --full. This creates the file tailwind.config.js. You may wish to save this file for later reference. Consider renaming it to tailwind.config-full.js.

Generate a new tailwind.config.js file by entering npx tailwindcss init and add customizations here. This file will be much shorter than the full version, making it easier to find your customizations. Values used by the provided CSS classes can be customized to change many styling aspects including colors, breakpoints, fonts, and more.

To change the actual colors used when white and black are specified, add a color property to the extend property as follows:

  theme: {
    extend: {
      colors: {
        black: "#222", // very dark gray
        white: "#ddd" // very light gray
      }

To define new, custom colors, add color properties to the extend property as follows:

  theme: {
    extend: {
      colors: {
        primary: "cornflowerblue",
        secondary: "orange"
      }

With these in place, we can use CSS class names like bg-primary and text-secondary.

To change the responsive breakpoints, modify the values below:

  theme: {
    ...
    screens: {
      sm: "640px",
      md: "768px",
      lg: "1024px",
      xl: "1280px"
    },

To change the fonts used when font-sans, font-serif, and font-mono are specified, modify the font name lists in the arrays below:

  theme: {
    ...
    fontFamily: {
      sans: [...],
      serif: [...],
      mono: [...]
    },

To register new fonts and add custom font sizes, specify the fontFamily and fontSize properties in the extend object. For example:

  theme: {
    extend: {
      fontFamily: {
        body: ['SomeFont1', 'SomeFont2']
      },
      fontSize: {
        "hero": "6rem"
      },

With this in place we can cause a header element to use it as follows:

<h1 class="text-hero">Welcome to My Page</h1>

The tailwind.config.js file defines a future property whose value is an object with boolean properties that are commented out. Uncomment these to get warnings about usage of features that will break in future releases.

Using With Frameworks

From the website for tailwind-merge, "If you use Tailwind CSS with a component-based UI renderer like React or Vue, you're probably familiar with the situation that you want to change some styles of a component, but only in a one-off case." tailwind-merge provides the function twMerge that takes any number of strings containing space-separated lists of CSS and Tailwind classes. It resolves any conflicts and returns a single string of class names.

Purging Unused CSS Classes

The purge configuration property can be modified to purge unused CSS classes. If this is not done, the generated CSS file will be massive. As of 10/13/2020, the size is 2413K uncompressed, 1967K minified, 190K gzipped, and 46K compressed with Brotli.

The purge property should be set to an array of glob patterns for file paths that can contain references to CSS classes. Tailwind will automatically check for references to Tailwind CSS classes in CSS files.

By default, unused CSS classes are only removed when the NODE_ENV environment variable is set to production. This is desirable. Otherwise every time a new Tailwind CSS class is used, another Tailwind build is required, which slows development.

To remove unused CSS classes regardless of the value of NODE_ENV, set the enabled property in the purge object to true.

For example, the purge property can be configured as follows::

  purge: {
    content: ['./public/**/*.html', './src/**.*.svelte'],
    enabled: true
  },

Minimizing CSS

To minimize the generated CSS, including removing comments, in order to make it smaller:

1. Enter npm install -D cssnano

2. Change the content of the postcss.config.js file to include :the following:

   const cssnano = require('cssnano');
   
   module.exports = {
     plugins: [
       require('tailwindcss'),
       require('autoprefixer'),
       cssnano({
         preset: 'default'
       })
     ]
   };
   

It may be desirable to only minimize CSS in production builds. To modify postcss.config.js to do this, see the end of How to setup Tailwind with PurgeCSS and PostCSS.

Serving Changes

There are many approaches to serve a site from local files and automatically refresh the browser when changes are detected. One simple approach is to use live-server.

To use live-server:

1. Enter npm install -g live-server
2. Enter live-server public where public contains an index.html file.
3. Browse localhost:8080.

VS Code Support

The VS Code extension Tailwind CSS IntelliSense provides autocomplete, syntax highlighting, and linting.

While entering Tailwind CSS class names, a popup displays all matching names and their definitions. For example, entering "upp" displays "uppercase - text-transform: uppercase".

To see the definition of a Tailwind CSS class that has already been entered, hover over its name.

A small color swatch is displayed in front of each Tailwind class name that represents a color.

The VS Code extension Tailwind Fold automatically folds the values of class attributes in HTML and className props in JSX. To see one of these values, move the cursor to its line. To toggle the folding behavior off and on, press ctrl-option-a.

To enable Emmet completions of Tailwind CSS class names, add the following in the VS Code settings.json file:

  "tailwindCSS.emmetCompletions": true

Icons

The makers of Tailwind created heroicons which is a website that provides a large collection of free SVG icons. Hover over an icon to expose buttons for downloading it in SVG or JSX. Paste this into an HTML file or React component.

The icons come in three variations with a viewBox of a specific size:

• Outline icons are 24x24 pixels and use a 1.5px stroke.
• Solid icons are 24x24 pixels and are filled.
• Mini icons are 20x20 and are filled.

By default the icons have the Tailwind classes w-6 and h-6 which makes them a 1.5rem square. To change the size of an icon, change these w and h classes.

To set the color of an icon, set its CSS color property.

When using React or Next.js, another option is to enter npm install @heroicons/react and import specific icons in component source files. For example:

import {BeakerIcon} from '@heroicons/react/24/solid';

Responsive Breakpoints

By default Tailwind uses the following responsive breakpoints:

These specify min-width values, so a mobile-first approach is used.

Precede Tailwind CSS class names with a breakpoint name and a colon to only apply the CSS class when the screen/window width is greater than or equal to the corresponding min-width value. For example: lg:m-4 applies a margin of 1rem only if the screen/window width is greater than or equal to 1024px.

Class names with no breakpoint prefix are used when the screen/window width is smaller than the largest prefix used. For example text-red md:text-green makes the text red for all widths less than 768px and green for all widths greater than or equal to 768px.

To show an element only when on a mobile device, use md:hidden. To hide an element when on a mobile device, use hidden md:block.

This approach for making UIs responsive is easier than writing CSS media queries.

The breakpoint values can be overridden by modifying the tailwind.config.js file as shown in the Configuration section.

Pseudo-class Variants

Tailwind supports many prefixes that can be added before class names, separated by a colon, that cause the class to only be applied when a certain condition holds.

These prefixes can be combined with responsive prefixes. For example, md:hover:border.

TODO: How can you enable a class when one of these conditions is NOT met?

Tailwind Directives

Tailwind supports several directives described below.

@apply

The @apply directive includes properties from any number of Tailwind classes in a custom CSS rule. This enables a set of Tailwind classes to be reused on several elements without repeating them.

For example, the following can be added to src/style.css after the @tailwind directives:

@layer components {
  .my-alert {
    @apply bg-red-400 inline-block p-4 rounded-full text-2xl text-white;
  }
}

After a Tailwind build, the my-alert class can be used to apply the styling of all the Tailwind classes specified with the @apply directive.

For example:

<div class="my-alert">Alert! Something is wrong.</div>

@layer

The @layer directive is used to add custom CSS rules to a specific bucket of Tailwind CSS rules.

@responsive

The @responsive directive generates responsive variants of custom CSS classes where the same styling is used for every breakpoint. To use different styling for some breakpoints, define media queries that override these.

@screen

The @screen directive creates a media query that utilizes a breakpoint value. For example, instead of writing a media query like this:

@media (min-width: 768px) {
  /* rules go here */
}

it can be written as follows to use the min-width value specified for the md breakpoint:

@screen md {
  /* rules go here */
}

@tailwind

The @tailwind directive is used to inject Tailwind CSS class definitions into the content of a CSS file. Earlier we saw this used in the src/style.css file.

@variants

The @variants directive is used to generate variants of your own CSS classes that are responsive or are only used when an element is hovered over, has focus, or is active.

Tailwind Functions

Tailwind currently provides a single function, theme.

theme Function

The theme function is used obtain values from the Tailwind config in CSS property values. For example, to use a shade of yellow from Tailwind in a custom CSS rule:

.warning {
  background-color: theme('colors.yellow.600');
}

Note that the string passed to the theme function is a dot-separated path to a Tailwind configuration value, not the name of a Tailwind class.

The rule above could also be written using the the @apply directive as follows:

.warning {
  @apply bg-yellow-600;
}

The theme function is primarily useful when a value will be used as part of a longer value or in a calculation using the CSS calc function.

Provided CSS Classes

The following sections list all the provided Tailwind CSS classes. There are a large number of them!

This same information is available in the official docs at tailwindcss.com/docs. It is included here in a more compact manner that is more easily searchable because they are all on a single page.

Many Tailwind class names end with a numeric strength value. Often this represents a multiple of 0.25rem. For example, the class p-4 adds padding of 1rem to all sides of an element. Class names for colors can specify strength values that are multiples of 100. For example, the class text-red-400 specifies a certain shade of red.

Many Tailwind class names support specifying an arbitrary value in square brackets. For example, the class p-[19px] adds padding of 19px to all sides of an element.

In class names that include -color, color should be replaced by one of gray, red, orange, yellow, green, teal, blue, indigo, purple, or pink.

In the "CSS Property" column of the tables below, lines where the property name start with -- are setting the value of a CSS variables (a.k.a. CSS custom properties).

Backgrounds

Borders

In the class names below, side can be one of the following:

In the class names below, corner can be one of the following:

Box Alignment

Box Sizing

Container

For example, lg:container or container.

Display

Effects

The box-shadow values set by the shadow classes are somewhat complicated. For details see the Box Shadow docs.

Flexbox

Also see the classes in the Box Alignment category.

Float and Clear

Grid

Interactivity

Object Fit

Object Position

Overflow

Overscroll Behavior

Position

Sizing

Spacing

SVG

Tables

Transforms

For all the classes in this section, n can be 0, 50, 75, 90, 95, 100, 105, 110, 125, or 150.

Transitions and Animation

The Tailwind transition-*, ease-*, and duration-* classes can be combined to easily create transitions from one CSS property value to another. For example, the following set of Tailwind classes on a button cause it to transition from having a red border and light red background to a green border and light green background on hover. The size of the button also increases slightly on hover.

<button className="
  border-2 px-2 py-1 rounded-full
  border-red-700 bg-red-300
  hover:border-green-700 hover:bg-green-300 hover:scale-110
  transition ease-linear duration-500
">
  Press Me
</button>

The animation and @keyframe values set by the animate classes are somewhat complicated. For details see the Animation docs.

Typography/Fonts

In the class name text-{color}-{n}, a number is required at the end. For example, text-red is not a valid Tailwind CSS class name.

Visibility

Z-Index

HyperUI

HyperUI is a collection of free UI components defined with Tailwind CSS classes and optionally AlpineJS directives.

There is no need to install anything. Just find a component to use from the website, copy its code, and paste in into your project.

Components are defined in a large number of categories including Auth Forms, Alerts, Badges, Breadcrumbs, Button Groups, Details Lists, Dividers, Dropdowns, Error Pages, Grids, Header, Inputs, Media, Pagination, Progress, Radio Groups, Selects, Side Menu, Stats, Steps, Tables, Tabs, Textareas, Toggles, and Vertical Menu.

There are also components that are specialized for eCommerce and Marketing.

Here is an example of a Toggle that only uses Tailwind classes:

<label
  for="AcceptConditions"
  class="relative h-8 w-14 cursor-pointer [-webkit-tap-highlight-color:_transparent]"
>
  <input type="checkbox" id="AcceptConditions" class="peer sr-only" />

  <span
    class="absolute inset-0 rounded-full bg-gray-300 transition peer-checked:bg-green-500"
  ></span>

  <span
    class="absolute inset-y-0 start-0 m-1 h-6 w-6 rounded-full bg-white transition-all peer-checked:start-6"
  ></span>
</label>

This code can be placed in a component for the specific framework being used (such as Astro or Svelte) to avoid pasting the same code in multiple places.