Creating custom utilities with addUtilities in Tailwind - Why You Should Know This

The Big Idea

What if you could create your own Tailwind classes that save hours of styling work?

The Scenario

Imagine you want a special button style that Tailwind doesn't have yet. You write the same CSS rules over and over in your stylesheet or inline styles for each button.

The Problem

This manual way is slow and messy. If you want to change the style later, you must find and update every place you wrote those rules. It's easy to miss some and cause inconsistent looks.

The Solution

Using addUtilities in Tailwind, you create your own reusable utility classes. Then you just add those classes in your HTML. Change the style once in your config, and all buttons update automatically.

Before vs After

✗ Before

.btn-special { background-color: #4caf50; padding: 1rem; border-radius: 0.5rem; }
<button class="btn-special">Click me</button>

✓ After

addUtilities({ '.btn-special': { backgroundColor: '#4caf50', padding: '1rem', borderRadius: '0.5rem' } }, { variants: [] })
<button class="btn-special">Click me</button>

What It Enables

You can build your own design system with consistent, easy-to-use classes that save time and avoid mistakes.

Real Life Example

A company wants all their buttons to have a unique green style. Instead of repeating CSS everywhere, they add a custom utility once and use it everywhere, making future updates simple.

Key Takeaways

Writing styles manually everywhere is slow and error-prone.

addUtilities lets you create reusable custom classes in Tailwind.

Change once, update everywhere for consistent design and easier maintenance.

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'