How to Refactor Custom Components for Tailwind 4 in Laravel Breeze

Why Refactoring Matters for Tailwind 4

Tailwind CSS v4 introduced changes that break or alter the behavior of many custom component styles. If you’ve built reusable Blade components or Vue components inside your Laravel Breeze app, chances are you’ll need to refactor them.

This guide walks through how to identify outdated styles, upgrade to Tailwind 4 conventions, and streamline your components for better performance and maintainability.

Don’t patch—refactor. Make your components lean, future-proof, and Tailwind 4-ready.

Key Takeaways

Understand how Tailwind 4 impacts custom components in Laravel Breeze
Learn specific examples for Blade and Vue refactoring
Use utility-first practices instead of bloated @apply blocks
Improve layout consistency and scalability

What’s Changed in Tailwind 4 That Impacts Custom Components

Layout and Spacing Utilities

Some spacing utilities like space-y-*, divide-*, and margin defaults were revised or deprecated. Custom cards and forms often break due to these updates.

Typography and Font Sizes

Text sizing (text-sm, text-base, text-lg) has been recalibrated. Custom headings and paragraphs may look different.

@apply Strictness

Tailwind 4 tightened rules for @apply. It now throws errors for unsupported or layered utilities.

Container Behavior

.container classes now require explicit max-w-* sizing to behave consistently.

Identifying Components That Need Refactoring

Start by scanning the following:

Blade components in resources/views/components
Vue 3 components in resources/js/Components
Any CSS classes using @apply in resources/css
Global layout files (app-layout.blade.php, guest-layout.blade.php)

Look for broken alignment, padding gaps, font-size differences, or missing container widths.

Step-by-Step: Refactor Blade Components for Tailwind 4

Refactor Example: `button.blade.php`

Before (Tailwind 3 style):

<button {{ $attributes->merge(['class' => 'bg-indigo-500 hover:bg-indigo-600 text-white py-2 px-4 rounded']) }}>
  {{ $slot }}
</button>

After (Tailwind 4 fix + @apply removed):

@props(['variant' => 'primary'])
@php
  $base = 'inline-flex items-center justify-center font-semibold text-white px-4 py-2 rounded';
  $variants = [
    'primary' => 'bg-indigo-600 hover:bg-indigo-700',
    'danger' => 'bg-red-500 hover:bg-red-600',
  ];
@endphp
<button {{ $attributes->merge(['class' => "$base {$variants[$variant]}"]) }}>
  {{ $slot }}
</button>

Refactor Example: `alert.blade.php`

Before:

<div class="bg-yellow-200 text-yellow-800 px-4 py-3 rounded">
  {{ $slot }}
</div>

After:

<div class="rounded px-4 py-3 text-sm bg-yellow-100 text-yellow-700 border border-yellow-300">
  {{ $slot }}
</div>

Replace `space-y-*` with Flex Gap

<div class="space-y-4">

Becomes:

<div class="flex flex-col gap-4">

Step-by-Step: Refactor Vue Components for Tailwind 4

Common Areas to Fix:

Replace outdated spacing with gap-*
Use utility-first logic inside templates
Avoid using custom CSS files for layout overrides

Example: `Card.vue`

<template>
  <div class="rounded-lg shadow-md p-4 bg-white">
    <slot />
  </div>
</template>

Improved version using flex gap:

<template>
  <div class="rounded-lg shadow p-6 bg-white flex flex-col gap-3">
    <slot />
  </div>
</template>

Tips for Cleaner, Maintainable Components

Use Flex + Gap instead of space utilities
Avoid excessive @apply—use inline classes where possible
Break components into smaller ones (Button, Icon, ModalHeader, etc.)
Centralize styles in shared PHP arrays or Vue props when dynamic
Document variants and slots to ensure consistency across teams

Refactor Checklist Table

Area	What to Refactor	Tailwind 4-Friendly Fix
Buttons	`@apply` + static classes	Inline utility with props
Layouts	`space-y-*`	Use `flex gap-*`
Typography	`text-sm`, `text-lg` changes	Audit all heading sizes
Containers	Missing `max-w-*`	Explicit widths added
Alerts	Inconsistent styling	Use border + background utilities

FAQ

Do I need to rewrite all my components? No. Focus on those broken or affected by Tailwind utility changes.

Can I still use @apply in Tailwind 4? Yes, but only with flat, supported class combinations. Avoid nesting.

Are Blade components better than Vue for UI? Blade is great for static content. Vue shines for interactivity. Use both where they fit best.

How do I test refactors visually? Use responsive design tools in your browser DevTools and Tailwind’s utility viewer extensions.

External Resources

Conclusion

Refactoring custom components for Tailwind 4 in Laravel Breeze might sound tedious, but it’s a golden opportunity to clean up bloated code and create flexible, scalable UI components.

Once you identify the most impacted areas—spacing, containers, typography, and @apply usage—you can apply modern patterns that align with Tailwind’s vision.

Whether you’re building with Blade, Vue, or both, take the time to refactor properly. Your code will thank you, your team will thank you, and your UI will look sharper than ever.