# Guide

# Installation

Install the package:

npm install @studiometa/tailwind-config@alpha --save-dev
1

# Usage

Import the configuration in your project's tailwind.config.js file.

// As is with no custom configuration
module.exports = require('@studiometa/tailwind-config');

// By adding the package's configuration as a preset and overriding it based on your project's needs
module.exports = {
  presets: [
    require('@studiometa/tailwind-config')
  ],
  // ...
}
1
2
3
4
5
6
7
8
9
10

TIP

preset extends the tailwindCSS 's base config object. If some parts of your tailwind config are redundant between projects, it can be a good strategy to load them from a preset.

Then, add the Tailwind directives in your global app.scss file:

// Import Tailwind's base the your project's base
@tailwind base;
// @import 'base/...';

// Import Tailwind's components then your project's components
@tailwind components;
// @import 'components/...';

// Import Tailwind's utilities then your project's utilities
@tailwind utilities;
// @import 'utilities/...';
1
2
3
4
5
6
7
8
9
10
11

WARNING

Do not forget to configure Purge CSSopen in new window in your project to remove all unused classes from the generated CSS files.

# How to and best practices

# Responsive

Tailwind uses a mobile first breakpoint system. It is recommended to use the utility classes unprefixed to target mobile and override them at larger breakpoints.

<div class="text-center s:text-left m:text-right"></div>
1

For behaviors related to a specific breakpoint it is recommended to undo this behavior by using a utility class that reapplies the basic behavior on a larger breakpoint.

<div class="bg-teal m:bg-red l:bg-teal"></div>
1

# Custom utility classes

# First method: Add it in the SCSS files

To manage the import of custom utility classes on Tailwind using a preprocessor you should place them in separate files and import them after Tailwind's utilities imports to avoid specificity issues.

@tailwind base;
@tailwind components;
@tailwind utilities;
@import 'utilities/custom-utility';
1
2
3
4

To create custom utility classes that can be used with the breakpoints defined in our configuration you should declare these utility classes in a @responsive directive.

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

@responsive {
  @variants hover, focus {
    .rotate-0 {
      transform: rotate(0deg);
    }
    .rotate-90 {
      transform: rotate(90deg);
    }
    .rotate-180 {
      transform: rotate(180deg);
    }
    .rotate-270 {
      transform: rotate(270deg);
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

The responsive versions of these utility classes will be automatically generated by Tailwind using the breakpoints entered in the configuration file.

<div class="rotate-0 hover:rotate-90"></div>
1

You can read the documentation on variants managementopen in new window for more detailed informations.

# Second method: By creating a plugin

We can add custom utilities with plugin. The following example generates the same classes as in the first method:

// tailwind.config.js
module.exports = {
  plugins: [
    ({ addUtilities }) => {
      const newUtilities = {
        '.rotate-0': {
          transform: 'rotate(0deg)',
        },
        '.rotate-90': {
          transform: 'rotate(90deg)',
        },
        '.rotate-180': {
          transform: 'rotate(180deg)',
        },
        '.rotate-270': {
          transform: 'rotate(270deg)',
        },
      };

      addUtilities(newUtilities, ['responsive', 'hover']);
    },
  ],
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Read the documentationopen in new window for more informations on plugins.

# Directives and Functions

# @applyopen in new window

Apply is useful for component extractionopen in new window when a pattern repeats itself. For buttons for example, it allows to centralize the properties of a component.

These declarations can be used alongside classic CSS declarations.

.btn {
  @apply font-bold py-2 px-4 rounded;
}
.btn-blue {
  @apply bg-blue-500 text-white;
}
.btn-blue:hover {
  @apply bg-blue-700;
  transform: translateY(-1px);
}
1
2
3
4
5
6
7
8
9
10

It is necessary to use interpolation to add !important to styles applied via the directive @apply:

.btn {
  @apply font-bold py-2 px-4 rounded #{!important};
}
1
2
3

The @apply directive cannot be used for statements about elements states or elemenrs responsiveness. Example of what you can't do:

.btn {
  @apply hover:bg-blue-500;
  @apply m:inline-block;
}
1
2
3
4

# @variantsopen in new window

It is possible to generate states utilities for our own utility classes by wrapping them in an @variants directive.

@variants focus, hover {
  .rotate-0 {
    transform: rotate(0deg);
  }
  .rotate-90 {
    transform: rotate(90deg);
  }
}
1
2
3
4
5
6
7
8

This will generate the following CSS:

.rotate-0 {
  transform: rotate(0deg);
}
.rotate-90 {
  transform: rotate(90deg);
}

.focus\:rotate-0:focus {
  transform: rotate(0deg);
}
.focus\:rotate-90:focus {
  transform: rotate(90deg);
}

.hover\:rotate-0:hover {
  transform: rotate(0deg);
}
.hover\:rotate-90:hover {
  transform: rotate(90deg);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

It is important to keep in mind that state variations will be generated in the order in which they are declared.

Finally, it is possible to generate customized variationsopen in new window to meet more specific needs.

# @responsiveopen in new window

It is possible to generate utility classes using the breakpoints defined in the configuration file with the @responsive directive.

@responsive {
  .bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
}
1
2
3
4
5

This will generate the following CSS:

.bg-gradient-brand {
  background-image: linear-gradient(blue, green);
}

/* ... */

@media (min-width: 768px) {
  .s\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}

@media (min-width: 1024px) {
  .m\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}

/*... */
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# @screenopen in new window

Instead of writing media queries with pixel values it is possible to use the @screen directive and refer to a breakpoint by its name. If we have a breakpoint s at 768px it's possible to use it in the following way:

@screen s {
  /* ... */
}
1
2
3

# theme()open in new window

The theme() function allows us to access the values entered in our configuration file.

.content-area {
  height: calc(100vh - theme('spacing.12'));
}

.btn-blue {
  background-color: theme('colors.blue.500');
}
1
2
3
4
5
6
7
Last Updated: 6/14/2021, 5:09:02 PM