[RFC] UX Html (Attributes)

[smnandre]

Tip

TL;DR: I'm proposing a new component in Symfony UX to manipulate HTML attributes.

--

I've been working for some time now on a UX HTML component. The starting point is an HTML attributes helper and builder: safe by default, fast, and easy to use and extend. The goal is simple: one solid foundation we can rely on across all Symfony UX packages, and that other packages or CMSes could also use or build on.

Recently, a nice PR with a different approach that was discussed a year ago has resurfaced in the Twig repository, and I think it's worth discussing the options.

The two approaches are almost opposites. One could even argue they are not solving the same problem. But I strongly believe this problem is not how we merge complex structured arrays or attributes.... The problem is that we use complex arrays for something that should be much simpler and more direct. Something that still allows conditionals, callables, and runtime customization, but can also offer more specific implementations (data-, aria-, Stimulus, etc.).

Best way to explain, I'm pasting my README below. Hopefully that's enough to kick off the discussion. I do not have a lot of time these days, so I'd rather not sink time into implementation details if the component itself is not something we want in UX.

Open to any questions, feedback, ideas, or suggestions :)

---

Why Symfony UX HTML?

The Problem

Building HTML attributes programmatically in PHP is tedious and error-prone:

// Traditional approach
$classes = ['btn', 'btn-primary'];
if ($isDisabled) {
    $classes[] = 'disabled';
}
$classAttr = htmlspecialchars(implode(' ', $classes));

$attrs = [];
$attrs[] = 'class="' . $classAttr . '"';
$attrs[] = 'id="my-button"';
if ($isDisabled) {
    $attrs[] = 'disabled';
}
$attrs[] = 'aria-label="' . htmlspecialchars($label) . '"';

echo '<button ' . implode(' ', $attrs) . '>Click</button>';

The Solution

Symfony UX HTML provides a fluent, type-safe, and secure API:

// in PHP code

$attrs = Attributes::create()
    ->id('my-button')
    ->class('btn btn-primary')
    ->toggle('disabled', $isDisabled)
    ->ariaLabel($label);

return sprintf('<button %s>Click</button>', $attrs);

{# in a Twig template #}

{% set attrs = attributes()
    .class('btn btn-primary')
    .ariaLabel('Submit form')
    .disabled(not post.isEnabled)
%}

<button{{ attrs }}>Submit</button>

Key Benefits

Feature	Traditional	UX HTML
Safety	Manual htmlspecialchars()	Auto-escaped ✅
Immutability	Mutable arrays	Immutable objects ✅
Readability	String concatenation	Fluent API ✅
Type Safety	Strings only	Typed methods ✅
Framework Integration	Manual	Twig/Stimulus helpers ✅

Perfect For

✅ Symfony/Twig applications
✅ Component libraries (buttons, forms, modals)
✅ Stimulus.js integration
✅ Building accessible HTML (ARIA helpers)
✅ Teams valuing code quality and DX

When NOT to Use

❌ Simple static HTML (overkill)
❌ Performance-critical hot paths with millions of attributes (never)
❌ Non-PHP projects

HTML Attributes is a fluent, immutable API for building and rendering HTML attribute strings in PHP. It was designed with performance, security, and developer experience in mind. Out of the box, it supports:

• Immutable Operations: Every modification returns a new instance.
• Fluent Builder API: Chain methods like set(), add(), remove(), and toggle().
• Magic Methods: Enable natural method calls (e.g. ->ariaLabel('Close') or ->disabled()).
• Namespaced Helpers: Dedicated helpers for ARIA, Stimulus, and generic data attributes.
• Secure Rendering: All output is properly escaped.
• High Performance: Optimized for the most common attribute operations.

Installation

composer require symfony/ux-html-attributes

Basic Usage

The library provides a single entry point to build an attribute collection and render it as a string:

Core API

use Symfony\UX\Html\Attribute\Attributes;

$attributes = Attributes::create()
    ->set('id', 'my-id')
    ->add('class', 'btn')
    ->add('class', 'btn-primary')
    ->toggle('disabled', true)
    ->remove('hidden');

DX-oriented API

$attr = Attributes::create()
    ->enableMagicMethods()
    ->href('/smnandre')                  // Named methods
    ->class('btn btn-sm btn-red')        // Set multiple classes
    ->rel('external me')                 // Join multiple values
    ->disabled(true)                     // Boolean attributes
    ->ariaLabel('Hello')                 // Aria namespaced helpers
    ->title('Ah < Bh');                  // String escaping

echo $attr->render();                    // Safe HTML rendering

<output
   href="/smnandre" class="btn btn-sm btn-red"
   rel="external me" disabled aria-label="Hello" title="Ah &lt; Bh" />

Twig Extension

Use the Twig helper to fluently compose attributes inside your templates:

{# templates/components/button.html.twig #}
{% set attrs = attributes()
    .class('btn btn-primary')
    .ariaLabel('Submit form')
    .disabled(not isEnabled)
%}

<button{{ attrs }}>Submit</button>

Features

Core API

Immutable

Each method returns a new instance.

Basic Methods:

• set(string $name, string|bool|null $value): self
  Create or replace an attribute. Use true for boolean attributes and false or null to remove them. Join arrays with spaces before passing.
• add(string $name, string|bool|null $value): self
  Append to an existing attribute. When both values are strings they are concatenated with a space.
• remove(string $name): self
  Remove an attribute from the collection.
• toggle(string $name, bool $condition): self
  Add the attribute when $condition is true, otherwise remove it.
• get(string $name): string|bool|null
  Fetch the raw value of an attribute.
• all(): array
  Return all attributes as an associative array.
• render(): string
  Render the attribute string with proper escaping.

Magic Methods:

Calls such as ->disabled(), ->ariaLabel('Close'), or ->foo('bar') are automatically converted to attribute names
in kebab-case and handled by the core API.

Namespaced Helpers

ARIA Attributes

Use the dedicated helper to set ARIA attributes:

$attributes->aria()->set('label', 'Close');
// Sets "aria-label" to "Close"

Data Attributes

Use the generic data helper to manage custom data-* attributes:

$attributes->data()->set('foo', 'bar');
// Sets "data-foo" to "bar"

Stimulus Attributes

Use the Stimulus helper to manage data-* attributes and controllers:

$attributes = Attributes::create()
    ->stimulus()->setController('dropdown')
    ->stimulus()->addController('modal')
    ->stimulus()->set('action', 'click->example#toggle');

echo $attributes->render();
// data-controller="dropdown modal" data-action="click->example#toggle"

Advanced Usage

Boolean and Array Values

Boolean attributes are enabled by passing true and removed when false or
null is used:

$attributes->disabled();       // Adds "disabled"
$attributes->hidden(false);    // Removes "hidden"
$attributes->hidden(true);     // Adds "hidden"

When working with arrays of values (e.g. classes) join them with spaces before
calling set() or add():

$classes = ['btn', 'btn-primary'];
$attributes->set('class', implode(' ', $classes));

echo $attributes->render();

Magic Methods

$attributes = Attributes::create()->enableMagicMethods();
$attributes->ariaLabel('Accessible Label'); // Sets aria-label="Accessible Label"
$attributes->foo('bar'); // Sets foo="bar"

> [!IMPORTANT]
> The magic methods are NOT enabled by default. Call `enableMagicMethods()` on the factory or an instance to enable them.

### Combining Attributes

```php
$attributes = Attributes::create()
    ->set('id', 'example')
    ->aria()->set('expanded', true)
    ->stimulus()->addController('dropdown');

echo $attributes->render();
// Output might be: id="example" aria-expanded="true" data-controller="dropdown"

Stimulus Helpers

$attributes->stimulus()->setController('modal');
$attributes->stimulus()->addController('dropdown');
$attributes->stimulus()->set('action', 'click->dropdown#toggle');

Future Features

Additional merging strategies and extensions are already planned for future releases (tailwind merge, CSS scoping, references...)

[...]

---

[Kocal]

Hi, and thanks for opening this RFC! 🙌🏻

The proposal is quite interesting overall, but there are a few aspects where I’m not fully convinced yet:

1. Magic methods

   1. Even if they are explicitly enabled via enableMagicMethods(), the Twig example uses attributes().class('btn btn-primary'), which seems to assume that magic methods are enabled. Is this intentional in the Twig extension?
   2. More generally, magic methods can make the developer experience harder, both for humans and tooling. Personally, I tend to be cautious with them.

2. Performance considerations
   Rendering attributes through many method calls (set, remove, toggle, get, etc.) could potentially have a performance impact. In many cases, these operations could be handled more simply with an array-based approach.

3. aria* methods
   I’m also not entirely sure about the added value of dedicated aria* methods.

We already have ComponentAttributes in TwigComponent. While it’s not perfect AFAIK, its array-based approach is very similar to what React and Vue.js do, which I see as a strong and proven pattern.

On the topic of TwigComponent: does it support attribute fallthrough and merging from a "parent" template? For example, with <twig:Foo class="bar">, is it possible to access or merge the class attribute inside the Foo component?

From my perspective, an attributes() Twig method could aim to:

1. Accept one or multiple array arguments.
2. Avoid rendering falsy values such as false or null.
3. Optionally (similar to ComponentAttributes), provide immutable chained methods like with or without, and be renderable as a string or usable as an iterable.
4. Handle class and style attributes in a Vue.js-like way (https://vuejs.org/guide/essentials/class-and-style.html), supporting
   string | list<string> | array<string, string|number|bool|null>.

Some examples:

<div{{ attributes({
    id: 'element',
    class: 'my-class',
}) }}></div>
{# <div id="element" class="my-class"></div> #}

<div{{ attributes({
    class: 'class-one class-two class-three',
    {# or #}
    class: ['class-one', { 'class-two': true, 'class-three': false }, 'class-four'],
    {# or #}
    class: { 'class-one': true, 'class-two': true, 'class-three': false, 'class-four': true },
}) }}></div>
{# <div class="class-one class-two class-four"></div> #}

<div{{ attributes({
    style: 'color: red; font-size: 14px;',
    {# or #}
    style: [ 'color: red', { 'font-size': '14px' } ],
    {# or #}
    style: { 'color': 'red', 'font-size': '14px' },
}) }}></div>
{# <div style="color: red; font-size: 14px;"></div> #}

<div{{ attributes({
    'aria-label': 'Close',
    'aria-hidden': 'true',
    'truthy-attr': true,
    'falsy-attr': false,
    'null-attr': null,
}) }}></div>
{# <div aria-label="Close" aria-hidden="true" truthy-attr="true"></div> #}

<div{{ attributes({ id: 'foo' }, { id: 'bar' }) }}></div>
{# <div id="bar"></div> #}

WDYT?

[smnandre]

So yours looks like the proposition made on the Twig repository... a very valid and interesting one... for who wants to manipulate arrays :)

Some reactions / comments, but I agree with you (except on the aria things where you contradict your

1) Magic methods

In Twig, all methods are magical, even more with TwigComponents, so even if I know some people won't like it, it offers in fact a lot of advantages: can be linted, compiled, optimised with Visitors, even cached and... typed :)

Also not all would be magic method: offering real methods for id, class, label, title, form, name and a few others is something that would offer some confort (especially for usage in PHP and not in Twig).

But this is the exact idea of extensions like Stimulus one (that allows only one "action" attribute with chained values, one "controller" attribute (same), but multiple "value" or "target" one... something impossible to handle without a dedicated implementation.

Extensibility is an absolute must-have for me if we want to be able to support multiple frameworks / tools / needs .. and not stack features with aveerage implementation 😅

2) Performance considerations

This will never ever have the tiniest impact, compared to other computation made in Twig (a bit) and in PHP / UX packages (a loooot). As long we use outerBlock / Scope i'm not even sure we should be allowed to talk about performances 😆

But let's say it does matter... well again, Twig is already using magic methods everywhere.

3) aria methods*

I don't get why class would and aria would not ... as long different attributes types exist and user want to be able to either append or prepend or merge ... we need custom implementation. That would have no performance coast and would allow us to respect the spec, helping developers passing correct values, etc.

But nothing would forbid you to use set('aria-labelled-by', true) even if... it should be written "aria-labelledby" and instead of a boolean, value must be a ref... two things you cannot control, type, or help developer do if they use arrays.

---

Rest of your code samples is litteraly how ComponentAttributes work / DX offered, right ? (genuine question 😅 )

Side (minor) note: ComponentAttributes is offered by TwigComponent, when it could be used for any UX package

---

Now it's not "one or the other", and I'm all for finding an interesting way to please everyone. Or to keep our current implementation that does work currently :)

[smnandre]

On the topic of TwigComponent: does it support attribute fallthrough and merging from a "parent" template? For example, with <twig:Foo class="bar">, is it possible to access or merge the class attribute inside the Foo component?

Of course, that is the whole point :) And this would allow decorating component for instance

[Kocal]

So yours looks like the proposition made on the Twig repository... a very valid and interesting one... for who wants to manipulate arrays :)

HTML attributes are more or less an array in the end... 😄

I don't get why class would and aria would not ... as long different attributes types exist and user want to be able to either append or prepend or merge ... we need custom implementation. That would have no performance coast and would allow us to respect the spec, helping developers passing correct values, etc.

I think we're mixing two things up here:

1. Handling class and style attributes, which are unique per element, where their values can be represented as an array (similary to what Vue.js does) for DX purpose.
2. Having aria() and data() helpers, that will generate multiple aria-* and data-* attributes. <troll>Also, since there are formaction, formenctype, formmethod (...) attributes, does it means that we will have form() too? 😛</troll>

An other question, what are the Twig equivalents for these examples?

$attributes->aria()->set('label', 'Close');

$attributes->data()->set('foo', 'bar');

$attributes = Attributes::create()
    ->stimulus()->setController('dropdown')
    ->stimulus()->addController('modal')
    ->stimulus()->set('action', 'click->example#toggle');

Rest of your code samples is litteraly how ComponentAttributes work / DX offered, right ? (genuine question 😅 )

More or less, ComponentAttributes does not handle array syntax for class and style attributes, have the hack for aria-* attributes with true value, and the support for Vue/Alpine special attribute-naming (due to nested attributes 😅).

My implementation would be more straightforward:

• accepts array of attributes
• ignore null attribute values
• ignore false attribute values except for aria-*
• support array syntax for class and style
• some methods to add/remove some attributes
• append/merge (if array) additional values to class and style attribute

Side (minor) note: ComponentAttributes is offered by TwigComponent, when it could be used for any UX package

💯

---

To finish, UX Html should accept an array of attributes when constructing the object, and make calling methods ->set() etc ... totally optional

[Kocal]

For reference, this is where/how React handle attributes:

• https://github.com/facebook/react/blob/main/packages/react-dom-bindings/src/client/DOMPropertyOperations.js, attributes data-* and aria-* are simply passed to the DOM if string, number (converted to string), true (converted to "true"), and removed if false/null/undefined.

And for Vue.js, TIL false values are rendered to "false" (where React removes them except for aria-*), and only null/undefined attribute value are removed:

• https://github.com/vuejs/core/blob/main/packages/runtime-dom/src/modules/attrs.ts
• https://github.com/vuejs/core/blob/main/packages/runtime-dom/src/modules/class.ts
• https://github.com/vuejs/core/blob/main/packages/runtime-dom/src/modules/style.ts

Chatting a bit with ChatGPT, here is a recap between how React/Vue handle attributes:

Attribute	Value	React	Vue
data-*	"string"	"string"	"string"
	number	"number"	"number"
	true	"true"	"true"
	false	not rendered	"false"
	null / undefined	not rendered	not rendered
aria-*	"string"	"string"	"string"
	number	"number"	"number"
	true	"true"	"true"
	false	"false"	"false"
	null / undefined	not rendered	not rendered
HTML boolean (disabled, checked)	true	present in DOM	present in DOM
	false	not rendered	not rendered
Other unknown attributes	any	passed through	passed through
class / style	-	manual merge	automatic merge

As we can see it's not as easy we can think, we must be clear about what we want to render, and on which attribute.
And I think it's important to align with either React or Vue, where people are used to that type of rendering, and not implement a third, different way.

[smnandre]

I've asked for another comprehensive (and somehow completing) review of the question to Perplexity here :
https://gist.github.com/smnandre/2fe94f875167c90511c97ce1c13eef72

/!\ It is long 😅

Its conclusion is not far from your ideas, but I love the very final sentence:

The key principle: explicit is better than implicit. Always provide a clear override mechanism rather than relying on implicit merging behavior.

Then, to be fair, this covers 90% (99%?) of the use cases.... but we had not feature requests from the 99% of the use cases, but from the specific ones (and the Stimulus ones)

🤷

[Kocal]

It looks like the document is twice its intended size, explaining why it's sooo long:

Then, to be fair, this covers 90% (99%?) of the use cases.... but we had not feature requests from the 99% of the use cases, but from the specific ones (and the Stimulus ones)

💯

But, we need to chose a strategy for the false and true (both booleans) attribute values. I think the Vue strategy is fine, it renders data-* attribute with false value and IMHO it makes sense.

An other question, what are the Twig equivalents for these examples?

$attributes->aria()->set('label', 'Close');

$attributes->data()->set('foo', 'bar');

$attributes = Attributes::create()
    ->stimulus()->setController('dropdown')
    ->stimulus()->addController('modal')
    ->stimulus()->set('action', 'click->example#toggle');

We still need to figure this out. I don't think that's an issue with:

attr({
    aria: { label: 'Close' },
    data: { foo: 'bar '},
    stimulus: { controller: 'dropdown', action: 'click->example#toggle' }
})

IMHO, let's keep your namespace things for aria-* and data-* attributes (like React/Vue do), and for Stimulus too since it's part of our ecosystem.

But it must be only an additional and optional feature.

Attributes aria-* and data-* set by ->set('data-foo', false) or data()->set('foo', false) should be rendered in the exact same way.

Personally, I'm not a fan about these namespaced attributes as I think it can lower the DX when debugging. In some project, finding the Twig template for a given HTML page could be hard, especially if your page is long.
You often use some specific code like classes, or data-* attributes to find the incriminated template, e.g. data-controller="tabs".
You won't find anything if you search data-controller="tabs" or data-controller in your project if you used the namespace feature. Instead, you will have to search 'controller', 'tabs', or controller: 'tabs' or 'controller': 'tabs', or ... you see what I mean.

WDYT? Thanks!

[smnandre]

But it must be only an additional and optional feature.

Yep!

IMHO, let's keep your namespace things for aria-* and data-* attributes (like React/Vue do), and for Stimulus too since it's part of our ecosystem.

What about ":" we use for nesting ? :|

Attributes aria-* and data-* set by ->set('data-foo', false) or data()->set('foo', false) should be rendered in the exact same way.

👍

Personally, I'm not a fan about these namespaced attributes

To me we need a way to have code/behaviour specific per attribute... but we 100% can find another way instead of explicit namespaces.

it can lower the DX when debugging.

One of my end goals here is related to my work project... where I would love to use such builder in Twig and remove the horrible DX of the form attributes 😅

So we agree there is (massive) room for improvment around here... let's find a solution that matches all our needs 🤝

[smnandre]

It looks like the document is twice its intended size, explaining why it's sooo long:

Fixed thanks

[Kocal]

IMHO, let's keep your namespace things for aria-* and data-* attributes (like React/Vue do), and for Stimulus too since it's part of our ecosystem.

What about ":" we use for nesting ? :|

I'm not sure to understand, can you share some code to help me to understand? Thanks!

[smnandre]

Currently we allow to pass nested attributes like this:

<twig:FooBar lorem:ipsum="sdfsfd" >

And that created problems with htmx, svelte, etc... and we had to hard-code some dedicated things for it..

What I was wondering here is if we hande only data-* aria-* or do we still want some (very partial) handling of this props/attributes drilling ?

Because if html_attributes does not handle it, we will have troubles ..

[Kocal]

Ah, nested attributes... 😅

Well, if we re-implement them, we will have the same issues with React/Vue/Alpine/another-library-that-use-:-in-their-attr, no?