Tailwind CSS v4 Arbitrary Values Breaking Changes - Square Brackets Not Working

After upgrading to Tailwind CSS v4, my arbitrary values using square brackets like w-[200px] and bg-[#ff0000] are no longer working. The classes are being purged or not generated at all. I'm getting console warnings about unknown classes and my custom values aren't being applied. What changed in v4 and how can I fix this?

Solution

Tailwind CSS v4 introduced significant changes to how arbitrary values are handled. The main issue is that arbitrary values now require explicit configuration in your CSS file using the new @theme directive.

Here's how to fix it:

Update your CSS file to use the new v4 syntax:

@import "tailwindcss";

@theme {
  --color-custom: #ff0000;
  --size-custom: 200px;
  --spacing-custom: 1.5rem;
}

Use the new arbitrary value syntax in your HTML:

<!-- Old v3 syntax (broken in v4) -->
<div class="w-[200px] bg-[#ff0000] p-[1.5rem]">

<!-- New v4 syntax -->
<div class="w-[--size-custom] bg-[--color-custom] p-[--spacing-custom]">

For dynamic values, use CSS custom properties:

@theme {
  --dynamic-width: 200px;
  --dynamic-color: #ff0000;
}

<div class="w-[--dynamic-width] bg-[--dynamic-color]">

Key changes in v4:

Arbitrary values must be defined in @theme block
Use -- prefix for custom properties
Square brackets now reference CSS variables
Better performance and tree-shaking
More explicit configuration required

This approach ensures your arbitrary values work correctly in Tailwind CSS v4.

Alternative #1

If you need truly dynamic arbitrary values that can't be predefined, you can use the new @arbitrary directive in v4:

@import "tailwindcss";

@arbitrary {
  /* Allow any width value */
  width: *;
  /* Allow any color value */
  background-color: *;
  /* Allow any spacing value */
  padding: *;
}

Then you can use the old syntax:

<div class="w-[200px] bg-[#ff0000] p-[1.5rem]">

However, this approach:

Reduces performance benefits of v4
Increases bundle size
Should be used sparingly
Only for truly dynamic values

Use this only when you absolutely need runtime-generated arbitrary values.

Alternative #2

For migration from v3 to v4, you can create a compatibility layer using CSS custom properties:

@import "tailwindcss";

@theme {
  /* Define common arbitrary values as CSS variables */
  --width-200: 200px;
  --width-300: 300px;
  --color-red: #ff0000;
  --color-blue: #0000ff;
  --spacing-4: 1rem;
  --spacing-8: 2rem;
}

/* Create utility classes for common arbitrary values */
@layer utilities {
  .w-200 { width: var(--width-200); }
  .w-300 { width: var(--width-300); }
  .bg-red-custom { background-color: var(--color-red); }
  .bg-blue-custom { background-color: var(--color-blue); }
  .p-4-custom { padding: var(--spacing-4); }
  .p-8-custom { padding: var(--spacing-8); }
}

Then update your HTML:

<!-- Old v3 -->
<div class="w-[200px] bg-[#ff0000] p-[1rem]">

<!-- New v4 with utilities -->
<div class="w-200 bg-red-custom p-4-custom">

This approach provides a smoother migration path while maintaining the benefits of v4.

Alternative #3

If you're using CSS-in-JS or dynamic styling, you might want to use the new @apply directive with CSS custom properties:

@import "tailwindcss";

@theme {
  --dynamic-width: 200px;
  --dynamic-color: #ff0000;
}

@layer components {
  .dynamic-card {
    @apply w-[--dynamic-width] bg-[--dynamic-color] p-4 rounded-lg;
  }
}

Then in your JavaScript:

// Update CSS custom properties dynamically
document.documentElement.style.setProperty('--dynamic-width', '300px');
document.documentElement.style.setProperty('--dynamic-color', '#00ff00');

And in your HTML:

<div class="dynamic-card">
  This card will use the dynamic values
</div>

This approach:

Allows runtime updates to arbitrary values
Maintains v4 performance benefits
Works well with JavaScript frameworks
Provides better type safety and IntelliSense