Creating custom utilities with addUtilities in Tailwind

Introduction

Custom utilities let you add your own styles easily. This helps you reuse special styles without writing CSS again and again.

You want a special color or size not in Tailwind by default.

You need a unique style for a project that Tailwind doesn't cover.

You want to keep your HTML clean by using short utility classes.

You want to share custom styles across many pages or components.

You want to add hover or focus styles that Tailwind doesn't provide.

Syntax

Tailwind

addUtilities({
  '.your-class': {
    'property': 'value',
    'property2': 'value2'
  },
  '.another-class': {
    'property': 'value'
  }
}, {
  variants: ['responsive', 'hover']
})

Use addUtilities inside your Tailwind plugin function.

The first argument is an object with class names and CSS properties.

Examples

Adds a .text-shadow class that applies a red shadow to text.

Tailwind

addUtilities({
  '.text-shadow': {
    'text-shadow': '2px 2px #ff0000'
  }
})

Adds a .skew-10deg class that skews an element on hover.

Tailwind

addUtilities({
  '.skew-10deg': {
    'transform': 'skewY(-10deg)'
  }
}, {
  variants: ['hover']
})

Adds a .border-3 class with 3px border width, usable with responsive prefixes like md:border-3.

Tailwind

addUtilities({
  '.border-3': {
    'border-width': '3px'
  }
}, {
  variants: ['responsive']
})

Sample Program

This example adds two custom utilities: .text-shadow for shadow on text, and .rotate-15 to rotate an element 15 degrees on hover. The button rotates smoothly when hovered.

Tailwind

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Custom Utilities Example</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <script>
    tailwind.config = {
      plugins: [
        function({ addUtilities }) {
          addUtilities({
            '.text-shadow': {
              'text-shadow': '2px 2px 4px rgba(0,0,0,0.5)'
            },
            '.rotate-15': {
              'transform': 'rotate(15deg)'
            }
          }, {
            variants: ['responsive', 'hover']
          })
        }
      ]
    }
  </script>
</head>
<body class="p-6">
  <h1 class="text-3xl font-bold text-shadow mb-4">Hello with Shadow</h1>
  <button class="bg-blue-500 text-white px-4 py-2 rounded hover:rotate-15 transition-transform">
    Hover me to rotate
  </button>
</body>
</html>

Important Notes

Custom utilities work like normal Tailwind classes and can have responsive or state variants.

Always test your custom utilities in different screen sizes to ensure responsiveness.

Use descriptive class names to keep your code easy to read.

Summary

Use addUtilities to create your own Tailwind classes with custom CSS.

Custom utilities help keep your HTML clean and styles reusable.

You can add variants like hover or responsive to your utilities.

Practice

1. What is the main purpose of using addUtilities in Tailwind CSS?

easy

A. To create custom CSS classes that can be reused in your HTML

B. To remove unused Tailwind CSS classes from the build

C. To automatically generate responsive breakpoints

D. To add JavaScript functionality to Tailwind components

Solution

1. Step 1: Understand the role of addUtilities

   addUtilities is used to define new CSS classes with custom styles that Tailwind does not provide by default.

2. Step 2: Compare with other options

   Options A, B, and D describe other Tailwind or unrelated features, not the purpose of addUtilities.

3. Final Answer:

   To create custom CSS classes that can be reused in your HTML -> Option A

4. Quick Check:

   addUtilities = create reusable custom classes [OK]

Hint: Remember: addUtilities adds new CSS classes [OK]

Common Mistakes:

• Confusing addUtilities with purge or remove features
• Thinking addUtilities adds JavaScript code
• Assuming it auto-generates responsive breakpoints

2. Which of the following is the correct syntax to add a custom utility class .text-shadow with text-shadow: 2px 2px #000; using addUtilities?

easy

A. addUtilities('.text-shadow { text-shadow: 2px 2px #000; }')

B. addUtilities({ '.text-shadow': { 'text-shadow': '2px 2px #000' } })

C. addUtilities({ textShadow: '2px 2px #000' })

D. addUtilities({ '.text-shadow': 'text-shadow: 2px 2px #000;' })

Solution

1. Step 1: Check the object format for addUtilities

   addUtilities expects an object where keys are class selectors and values are objects of CSS properties.

2. Step 2: Validate each option

   addUtilities({ '.text-shadow': { 'text-shadow': '2px 2px #000' } }) correctly uses an object with selector key and CSS property object value. Options B and D use incorrect formats (string or wrong value type). addUtilities({ textShadow: '2px 2px #000' }) misses the selector key.

3. Final Answer:

   addUtilities({ '.text-shadow': { 'text-shadow': '2px 2px #000' } }) -> Option B

4. Quick Check:

   addUtilities needs selector: CSS object [OK]

Hint: Use object with selector keys and CSS property objects [OK]

Common Mistakes:

• Passing CSS as a string instead of an object
• Omitting the selector key for the utility
• Using camelCase for CSS properties instead of kebab-case

3. Given this Tailwind plugin code snippet, what CSS class will be generated?

addUtilities({
  '.custom-border': {
    'border-width': '3px',
    'border-color': '#f00'
  }
})

medium

A. A class named .border-custom with 3px red border

B. A class named .custom-border with 1px black border

C. A class named .custom-border with 3px red border

D. No class will be generated due to syntax error

Solution

1. Step 1: Identify the class name and CSS properties

   The key '.custom-border' defines the class name. The CSS properties set border width to 3px and border color to red (#f00).

2. Step 2: Confirm no syntax errors

   The object syntax is correct, so the class will be generated as described.

3. Final Answer:

   A class named .custom-border with 3px red border -> Option C

4. Quick Check:

   Selector and CSS properties match output class [OK]

Hint: Class name is the object key, CSS inside is the style [OK]

Common Mistakes:

• Confusing class name with CSS property names
• Assuming default border width or color
• Thinking syntax error prevents generation

4. Identify the error in this Tailwind plugin code that tries to add a .bg-gradient utility:

addUtilities({
  '.bg-gradient': 'background: linear-gradient(to right, #000, #fff);'
})

medium

A. Missing semicolon after addUtilities call

B. Class selector should not start with a dot

C. The property name 'background' is invalid in Tailwind

D. CSS properties must be inside an object, not a string

Solution

1. Step 1: Check the value type for the class key

   The value for '.bg-gradient' must be an object with CSS properties, not a string.

2. Step 2: Validate other options

   Class selectors should start with a dot (correct here). 'background' is a valid CSS property. Semicolon after function call is optional in JavaScript.

3. Final Answer:

   CSS properties must be inside an object, not a string -> Option D

4. Quick Check:

   CSS properties need object format [OK]

Hint: Use object for CSS properties, not string [OK]

Common Mistakes:

• Passing CSS as a string instead of an object
• Removing the dot from class selector
• Thinking semicolon is mandatory after addUtilities

5. You want to create a custom utility .hover-scale that scales an element to 1.1 times its size on hover using addUtilities. Which is the correct way to add this utility with hover variant support?

hard

A. addUtilities({ '.hover-scale': { transform: 'scale(1.1)' } }, { variants: ['hover'] })

B. addUtilities({ '.hover-scale:hover': { transform: 'scale(1.1)' } })

C. addUtilities({ '.hover-scale': { ':hover': { transform: 'scale(1.1)' } } })

D. addUtilities({ '.hover-scale': { transform: 'scale(1.1)' } }, { variants: ['responsive'] })

Solution

1. Step 1: Understand how to add variants with addUtilities

   Variants like 'hover' are added as a second argument object with a variants array.

2. Step 2: Check each option's approach

   addUtilities({ '.hover-scale': { transform: 'scale(1.1)' } }, { variants: ['hover'] }) correctly adds the utility and enables hover variant. addUtilities({ '.hover-scale:hover': { transform: 'scale(1.1)' } }) incorrectly tries to put :hover in the selector key. addUtilities({ '.hover-scale': { ':hover': { transform: 'scale(1.1)' } } }) nests :hover inside CSS object, which is invalid. addUtilities({ '.hover-scale': { transform: 'scale(1.1)' } }, { variants: ['responsive'] }) uses 'responsive' variant, not hover.

3. Final Answer:

   addUtilities({ '.hover-scale': { transform: 'scale(1.1)' } }, { variants: ['hover'] }) -> Option A

4. Quick Check:

   Variants go in second argument as array [OK]

Hint: Add variants as second argument with variants array [OK]

Common Mistakes:

• Putting :hover inside selector string
• Nesting :hover inside CSS object
• Using wrong variant name like 'responsive' instead of 'hover'