Creating custom utilities with addUtilities in Tailwind - Performance Optimization Steps

Performance: Creating custom utilities with addUtilities

MEDIUM IMPACT

This affects the CSS bundle size and how quickly styles are applied during page load.

Adding custom CSS utilities for repeated styles

Tailwind

module.exports = {
  plugins: [
    function({ addUtilities, e, theme, variants }) {
      const shadows = theme('boxShadow')
      const utilities = Object.entries(shadows).map(([name, value]) => ({
        [`.${e(`custom-shadow-${name}`)}`]: { 'box-shadow': value }
      }))
      addUtilities(utilities, variants('boxShadow'))
    }
  ]
}

Generates utilities dynamically from existing theme values, avoiding duplication and reducing CSS size.

📈 Performance GainSaves 30-50kb in CSS bundle, improving LCP by 50-100ms

Adding custom CSS utilities for repeated styles

Tailwind

module.exports = {
  plugins: [
    function({ addUtilities }) {
      addUtilities({
        '.custom-shadow': {
          'box-shadow': '0 4px 6px rgba(0,0,0,0.1)',
        },
        '.custom-shadow-lg': {
          'box-shadow': '0 10px 15px rgba(0,0,0,0.2)',
        },
        '.custom-shadow-xl': {
          'box-shadow': '0 20px 25px rgba(0,0,0,0.3)',
        },
        // ... many more similar utilities
      })
    }
  ]
}

Adding many similar utilities manually bloats the CSS file size and slows down page load.

📉 Performance CostAdds 50-100kb to CSS bundle, increasing LCP by 100-200ms on slow networks

Performance Comparison

Pattern	DOM Operations	Reflows	Paint Cost	Verdict
Manual many custom utilities	No extra DOM nodes	0 reflows	High paint cost due to large CSS	[X] Bad
Dynamic utilities from theme	No extra DOM nodes	0 reflows	Lower paint cost with smaller CSS	[OK] Good

Rendering Pipeline

Custom utilities added via addUtilities become part of the CSS bundle loaded by the browser. Larger CSS files delay Style Calculation and Paint stages, impacting the time until the page visually stabilizes.

→Style Calculation

→Layout

→Paint

⚠️ BottleneckStyle Calculation due to larger CSS size

Core Web Vital Affected

LCP

This affects the CSS bundle size and how quickly styles are applied during page load.

Optimization Tips

1Avoid manually adding many similar utilities to keep CSS small.

2Generate utilities dynamically from theme values when possible.

3Monitor CSS bundle size to maintain fast Largest Contentful Paint.

Performance Quiz - 3 Questions

What is a main performance risk when adding many custom utilities manually with addUtilities?

A Adding extra DOM nodes to the page

B Increasing CSS bundle size and delaying page load

C Causing JavaScript errors during runtime

D Reducing accessibility of the page

DevTools: Network

How to check: Open DevTools > Network tab, reload page, filter by CSS files, and check the size of the CSS bundle.

What to look for: Look for large CSS file sizes that delay page load and increase LCP.

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'