nicksdot/blade-html-attributes

Laravel Blade directives for conditionally rendering HTML attributes

0.1.0 2025-10-18 03:30 UTC

Requires

• php: ^8.1
• illuminate/support: ^10.0|^11.0|^12.0
• illuminate/view: ^10.0|^11.0|^12.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.88.2
• larastan/larastan: ^3.7.2
• nicksdot/phpstan-phpstorm-error-identifiers: ^0.2.0
• orchestra/testbench: ^v10.6.0
• phpstan/phpstan: ^2.1.31
• phpstan/phpstan-deprecation-rules: ^2.0.3
• phpstan/phpstan-strict-rules: ^2.0.7
• phpunit/phpunit: ^12.4.1

MIT

• Nick Sdot

README

A Laravel package that provides Blade directives for conditionally rendering HTML attributes.

Installation

composer require nicksdot/blade-html-attributes

The package will auto-register the service provider.

Available Directives

Behaviour Matrix

Note: Rows in bold show special operator = & ! behaviour.

Value	@attr	@data	@aria	@flag
('foo', "bar")	foo="bar"	data-foo="bar"	aria-foo="bar"	foo
('foo', "1")	foo="1"	data-foo="1"	aria-foo="1"	foo
('foo', 1)	foo="1"	data-foo="1"	aria-foo="1"	foo
('foo', true)	foo	data-foo	aria-foo="true"	foo
('foo=', true)	foo="true"	data-foo="true"	aria-foo="true"	foo
('foo', false)	(nothing)	(nothing)	aria-foo="false"	(nothing)
('foo=', false)	foo="false"	data-foo="false"	aria-foo="false"	(nothing)
('!foo', false)	(throws)	(throws)	(nothing)	(throws)
('foo', "0")	foo="0"	data-foo="0"	aria-foo="0"	(nothing)
('foo', 0)	foo="0"	data-foo="0"	aria-foo="0"	(nothing)
('foo', '')	(nothing)	(nothing)	(nothing)	(nothing)
('foo=', '')	foo=""	data-foo=""	(nothing)	(nothing)
('foo', ' ')	(nothing)	(nothing)	(nothing)	(nothing)
('foo=', ' ')	foo=" "	data-foo=" "	(nothing)	(nothing)
('foo', null)	(nothing)	(nothing)	(nothing)	(nothing)

Gotchas:

• @attr and @data allow the = suffix (e.g., @attr('foo=', $value)) to force values (always render with ="value", even for booleans and empty strings)
• @aria allows the ! prefix (e.g., @aria('!foo', $value)) to negate false values for removing attribute entirely.

Descriptions

• @attr: By default, true renders as a boolean flag (attribute name only), and false/empty/whitespace-only/null render nothing. With the force-value operator (= suffix like 'foo='), always renders with values including "true", "false", and empty strings.

• @data: Same as @attr but automatically prefixes attribute names with data-.

• @aria: By default, renders all values including "true" and "false" (never as boolean flags). Never renders empty or whitespace-only strings. With the negation operator (! prefix like '! foo'), false the attribute is completely removed instead of rendering as "false".

• @flag: Outputs just the attribute name without a value (boolean flag), for truthy values only. Follows HTML spec for boolean attributes like disabled, checked, required or data-foo.

Examples

@attr Directive

{{-- Before / After --}}
<a href="{{ $link->route }}" @if($link->title) title="{{ $link->title }} @endif" @if($link->rel) rel="{{ $link->rel }} @endif"></a>
<a href="{{ $link->route }}" @maybe('title', $link->title) @maybe('rel', $link->rel)></a>

{{-- Before / After --}}
<input @if($value !== null) value="{{ $value }}" @endif />
<input @attr('value=', $value) />

{{-- Before / After --}}
<select @if($size) size="{{ $size }}" @endif></select>
<select @attr('size', $size)></select>

{{-- Force rendering booleans as string value --}}
<div @attr('contenteditable=', true)>
    Edit me (renders as `contenteditable="true"`)
</div>

@data Directive

{{-- Before / After --}}
<div @if($id) data-id="{{ $id }}" @endif @if($value) data-value="{{ $value }}" @endif></div>
<div @data('id', $id) @data('value', $value)></div>

{{-- Before / After --}}
<button @if($toggle) data-toggle @endif></button>
<button @data('toggle', $toggle)></button>

{{-- Force rendering booleans as string value --}}
<button @data('toggle=', $toggle)>
    Click (renders as `data-toggle="true"`)
</button>

@aria Directive

{{-- Before / After --}}
<button @if($label) aria-label="{{ $label }}" @endif @if($hidden) aria-hidden="{{ $hidden }}" @endif></button>
<button @aria('label', $label) @aria('hidden', $hidden)></button>

{{-- Before / After --}}
<div @if($label && $label !== '') aria-label="{{ $label }}" @endif></div>
<div @aria('label', $label)></div>

{{-- Before / After --}}
<div @if($hidden) aria-hidden="true" @endif></div>
<div @aria('!hidden', $hidden)></div>

@flag Directive

{{-- Before --}}
<button @if($isDisabled) disabled @endif>Submit</button>

{{-- After --}}
<button @flag('disabled', $isDisabled)>Submit</button>

{{-- Multiple flag attributes --}}
<input type="checkbox" @flag('checked', $isChecked) @flag('required', $isRequired) />

Requirements

• PHP 8.1+
• Laravel 10.0+

License

This package is open-sourced software licensed under the MIT licence.

Credits

• Nick