spatie/laravel-html

HTML elements (found in the Spatie\Html\Elements namespace) are typically created using a Spatie\Html\Html builder instance.

Immutability: Element instances are immutable. When you call a fluent method to modify attributes or contents, it returns a new instance rather than modifying the existing one. To capture changes, you must assign the result to a variable.

$icon = html()->span()->class('fa');

// This returns a NEW instance with both classes applied
$icon->class('fa-eye'); // '<span class="fa fa-eye"></span>'

// This returns a NEW instance with the slash class applied
$icon->class('fa-eye-slash'); // '<span class="fa fa-eye-slash"></span>'

html()->span()->text('Hello world!');

The HTML builder can bind to a model to automatically populate input values. By calling html()->model($model), subsequent input elements will automatically pull their values from the provided model's properties.

A "model" can be any object that implements ArrayAccess, such as an Eloquent model or a plain associative array.

{{ html()->model($user) }}

{{ html()->input('name') }}

All Spatie\Html\Elements provide a fluent API for building HTML. Methods can be chained together, and because elements are immutable, every method returns a new instance of the Element. This allows you to preserve the original element if needed.

Additionally, you can use the If suffix on any method (e.g., classIf(), attributeIf()) to execute that method only if the first parameter is true.

echo Div::classIf(true, 'row');
// "<div class="row"></div>"

echo Div::classIf(false, 'row');
// "<div></div>"

echo Div::attributeIf(50 > 100, 'data-custom', 'Attribute value');
// "<div></div>"

You can link the HTML builder to an Eloquent model using the model() method. When a model is active, form fields will automatically attempt to use the values from the corresponding model attributes for their value attribute.

To stop using the current model for subsequent elements, use the endModel() method.

$user = new User(['name' => 'Johnny']);
html()->model($user);
echo html()->text('name');
// Outputs: <input type="text" name="name" value="Johnny">

The package is built around two main components:

1. Spatie\™\Html\\Elements classes: These represent individual HTML elements. They are 'stateless' and have no knowledge of the outside world (like requests or models) on their own.
2. Spatie\Html\Html builder: This is the central orchestrator. It uses builder methods to create Element instances. Crucially, the builder provides context by coupling elements to Laravel's requests, sessions, and models (e.g., automatically pulling 'old' input values or model attributes).

You can chain fluent methods from the Element classes directly onto the Html builder methods because the builder returns Element instances.

To make your custom Html class available throughout your application via the package's standard injection or helpers, register it as a singleton in your AppServiceProvider (or any other service provider). You must bind Spatie\Html\Html::class to your custom class implementation.

<?php

namespace App\Providers;

use App\Services\HtmlExtended;
use Illuminate\Support\ServiceProvider;
use Spatie\Html\Html;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        $this->app->singleton(Html::class, HtmlExtended::class);
    }
}

After installing, you must register the Spatie\Html\HtmlServiceProvider::class in your application configuration to enable the package features.

// For Laravel versions prior to 11, add to config/app.php
'providers' => [
    ...
    Spatie\Html\HtmlServiceProvider::class,
];

// For Laravel 11, add to bootstrap/providers.php
return [
    ...
    Spatie\Html\HtmlServiceProvider::class,
];

For easier model-driven forms, use modelForm() to open a form that is automatically coupled to a model, and closeModelForm() to close it. This is a convenience wrapper around model() and endModel().

{{ html()->modelForm($user, 'PUT', '/update-url')->open() }}

    {{ html()->text('name') }}
    {{ html()->email('email')}}

{{ html()->closeModelForm() }}

Upgrading from version 1 to version 2 is generally non-breaking via composer update, but be aware of the following:

• html() helper: The package now provides a global html() function by default. If you have a custom html() method defined in your application, you must remove it to avoid conflicts.
• Typehints: Various typehints were removed to improve flexibility (e.g., allowing arrays for multiple select elements). If you have extended any classes from the package, you will need to update your method signatures to match the new, less restrictive typehints.

Install the package using Composer:

composer require spatie/laravel-html

To use the Html facade with a shorter name, optionally register an alias in your config/app.php file:

// config/app.php
'aliases' => [
    ...
    'Html' => Spatie\Html\Facades\Html::class,
];