Building Reusable Laravel Blade Components: A Developer's Guide
Building reusable Blade components is one of the most powerful ways to improve your Laravel application's maintainability and development speed. When done right, components eliminate code duplication, enforce consistent design patterns, and make your UI predictable across your entire application.
In this guide, we'll explore proven strategies for creating Blade components that stand the test of time, using practical examples and real-world patterns.
Start with Clear Component Contracts
The foundation of any reusable component is a well-defined interface. Your component should have a clear purpose and predictable behavior, regardless of where it's used.
Define Your Props Explicitly
Always use the @props directive to define your component's expected inputs. This serves as documentation and helps catch errors early:
{{-- resources/views/components/status-badge.blade.php --}}
@props([
'status' => 'pending',
'size' => 'md',
'variant' => 'default'
])
@php
$classes = match($status) {
'active' => 'bg-green-100 text-green-800 border-green-200',
'pending' => 'bg-yellow-100 text-yellow-800 border-yellow-200',
'inactive' => 'bg-red-100 text-red-800 border-red-200',
default => 'bg-gray-100 text-gray-800 border-gray-200'
};
@endphp
<span {{ $attributes->merge(['class' => "px-3 py-1 rounded-full text-sm font-medium border {$classes}"]) }}>
{{ $slot }}
</span>
This approach makes your component self-documenting and provides sensible defaults. Compare this to a premium component library like Aura UI, where components like <x-aura::badge> follow similar patterns with extensive customization options.
Embrace Attribute Merging
The $attributes object is your friend for creating flexible components. Use merge() to combine default classes with user-provided ones:
{{-- Allow custom classes while maintaining base functionality --}}
<button {{ $attributes->merge([
'type' => 'button',
'class' => 'inline-flex items-center px-4 py-2 rounded-md font-medium transition-colors'
]) }}>
{{ $slot }}
</button>
Design for Composition Over Configuration
Instead of creating monolithic components with dozens of props, build smaller, composable pieces that work together.
The Card Component Pattern
Rather than building one massive card component, create a family of related components:
{{-- resources/views/components/card/index.blade.php --}}
@props(['padding' => true])
<div {{ $attributes->merge(['class' => 'bg-white rounded-lg shadow-sm border border-gray-200' . ($padding ? ' p-6' : '')]) }}>
{{ $slot }}
</div>
{{-- resources/views/components/card/header.blade.php --}}
<div {{ $attributes->merge(['class' => 'flex items-center justify-between mb-4']) }}>
{{ $slot }}
</div>
{{-- resources/views/components/card/title.blade.php --}}
<h3 {{ $attributes->merge(['class' => 'text-lg font-semibold text-gray-900']) }}>
{{ $slot }}
</h3>
Now you can compose cards flexibly:
<x-card>
<x-card.header>
<x-card.title>User Profile</x-card.title>
<x-aura::button size="sm" variant="outline">Edit</x-aura::button>
</x-card.header>
<div class="space-y-4">
<p>User details go here...</p>
</div>
</x-card>
Handle State and Interactivity Gracefully
When building components that need to manage state or interact with Livewire, follow these patterns:
Livewire-Aware Components
For components that work with Livewire properties, use wire:model.live for real-time updates:
{{-- resources/views/components/search-input.blade.php --}}
@props([
'placeholder' => 'Search...',
'debounce' => '300ms'
])
<div class="relative">
<input
{{ $attributes->merge([
'type' => 'text',
'class' => 'w-full pl-10 pr-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent',
'placeholder' => $placeholder
]) }}
@if($attributes->has('wire:model'))
wire:model.live.debounce.{{ $debounce }}="{{ $attributes->get('wire:model') }}"
@endif
>
<svg class="absolute left-3 top-2.5 h-5 w-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
</svg>
</div>
Implement Consistent Styling Systems
Create a cohesive design system by establishing consistent patterns for variants, sizes, and states.
Variant-Based Styling
Use PHP's match expression for clean variant handling:
@php
$buttonClasses = match($variant) {
'primary' => 'bg-blue-600 hover:bg-blue-700 text-white border-transparent',
'secondary' => 'bg-gray-600 hover:bg-gray-700 text-white border-transparent',
'outline' => 'bg-transparent hover:bg-gray-50 text-gray-700 border-gray-300',
'ghost' => 'bg-transparent hover:bg-gray-100 text-gray-700 border-transparent',
default => 'bg-gray-100 hover:bg-gray-200 text-gray-900 border-gray-300'
};
$sizeClasses = match($size) {
'xs' => 'px-2 py-1 text-xs',
'sm' => 'px-3 py-1.5 text-sm',
'md' => 'px-4 py-2 text-sm',
'lg' => 'px-6 py-3 text-base',
'xl' => 'px-8 py-4 text-lg'
};
@endphp
This approach mirrors how professional component libraries like Aura UI handle their extensive variant systems across components like <x-aura::button>, <x-aura::card>, and <x-aura::badge>.
Optimize for Performance
Avoid Heavy Computations in Views
Move complex logic to component classes or view composers:
<?php
// app/View/Components/UserAvatar.php
namespace App\View\Components;
use Illuminate\View\Component;
class UserAvatar extends Component
{
public function __construct(
public $user,
public string $size = 'md'
) {}
public function initials(): string
{
return collect(explode(' ', $this->user->name))
->map(fn($name) => strtoupper(substr($name, 0, 1)))
->take(2)
->join('');
}
public function avatarUrl(): ?string
{
return $this->user->avatar_url
? Storage::url($this->user->avatar_url)
: null;
}
public function render()
{
return view('components.user-avatar');
}
}
Cache Expensive Operations
For components that perform database queries or API calls, implement caching:
public function stats()
{
return Cache::remember(
"user-stats-{$this->user->id}",
now()->addMinutes(15),
fn() => $this->user->calculateStats()
);
}
Test Your Components
Reusable components should be thoroughly tested to ensure they work consistently across different contexts:
// tests/Feature/Components/StatusBadgeTest.php
test('status badge renders with correct classes', function () {
$component = $this->blade('<x-status-badge status="active">Active User</x-status-badge>');
$component->assertSee('Active User')
->assertSeeInOrder(['bg-green-100', 'text-green-800']);
});
test('status badge accepts custom attributes', function () {
$component = $this->blade('<x-status-badge status="pending" data-testid="badge">Pending</x-status-badge>');
$component->assertSee('data-testid="badge"', false);
});
Documentation and Developer Experience
Great components are self-documenting, but don't skip proper documentation:
{{--
@component('status-badge')
@description A status indicator badge with predefined color schemes
@props([
'status' => 'The status type (active|pending|inactive)',
'size' => 'Badge size (sm|md|lg)',
'variant' => 'Visual variant (default|solid|outline)'
])
@example
<x-status-badge status="active">Online</x-status-badge>
<x-status-badge status="pending" size="lg">Processing</x-status-badge>
--}}
Conclusion
Building reusable Blade components is an investment in your application's future. By following these patterns—clear contracts, composition over configuration, consistent styling systems, and thorough testing—you'll create components that are both powerful and maintainable.
Remember that great component libraries like Aura UI didn't happen overnight. They evolved through careful attention to developer experience, consistent patterns, and real-world usage. Start small, iterate based on feedback, and gradually build up your component library.
The key is to think of components not just as UI elements, but as building blocks that enable your team to move faster while maintaining consistency and quality across your entire application.
