README

Twig Components for HTML5 Elements

This is a Symfony Bundle which adds pre-built, typesafe, auto-generated Twig Components for all HTML5 elements. It comes with full WCAG, ARIA support, also adds support for Alpine.js attributes. It makes use of Extended HTMLDocument which is a schema-first library that improves HTML5 support in PHP 8.4. Mainly used for validation of immutable enum attributes.

This is especially useful when writing anonymous Twig Components enforcing standards-compliance, always-valid HTML5.

Features

• Symfony UX Integration: Native Symfony Twig Component support
• ARIA Compliant: Complete ARIA attribute support with proper validation
• Auto-Generated: Consistent API across all HTML5 elements via schema-first approach
• Enum Validation: Static attribute validation for HTML compliance
• Modern PHP: Requires PHP 8.4+ for DOM\HTMLDocument features

Requirements

• PHP 8.4 – the underlying Extended HTMLDocument library is built upon PHPs DOM\HTMLDocument which is available since PHP 8.4+

Since only the Enums are used for attribute validation here, adding support for older PHP versions could be done easily if it's needed or requested.

Installation

composer require vardumper/html5-twig-component-bundle

The bundle includes automatic service registration - no additional configuration needed!

Configuration

When installed via Symfony Flex, this bundle is automatically configured by the recipe in flex/recipe.

If you are not using Symfony Flex, register the bundle manually in config/bundles.php:

# config/bundles.php
return [
    // ...
    Html\TwigComponentBundle\HtmlTwigComponentBundle::class => ['all' => true],
];

Then tell Symfony where the Twig Components are located. Edit config/packages/twig_component.yaml and add the following:

# config/packages/twig_component.yaml
twig_component:
    defaults:
        Html\TwigComponentBundle\Twig\: '%kernel.project_dir%/vendor/vardumper/html5-twig-component-bundle/src/Twig/'

All Twig Components are automatically discovered and registered through the bundle's DependencyInjection extension. No manual service configuration required!

Usage

Use any HTML element as a Twig Component:

<twig:Blockquote cite="https://example.com">
    This is a quote from example.com
</twig:Blockquote>

<twig:Button role="button" type="submit">
    Submit Form
</twig:Button>

<twig:Input type="email" name="email" required />

Use in anonymous Twig Components

{# templates/components/Teaser.html.twig #}
<twig:Div class="teaser"> 
    <twig:H3>{{ headline }}</twig:H3>
    <twig:P>{{ content }}</twig:P>
    <twig:A role="button" href="{{ buttonLink }}" title="{{ buttonText }}">{{ buttonText }}</twig:A>
</twig:Div>

which can then be used in pages:

{# templates/page.html.twig #}
{% for item in teasers %}
    <twig:Teaser 
        headline="{{ item.headline }}" 
        content="{{ item.content }}" 
        buttonLink="{{ item.buttonLink }}" 
        buttonText="{{ item.buttonText }}">
    </twig:Teaser>
{% endfor %}

Passing arrays as component props

You can pass associative arrays to component props using the : notation. For example to pass data-* attributes to the component:

<twig:Div :dataAttributes="{'role': 'article'}">
    Hello world
</twig:Div>

This will render a data-role="article" attribute on the generated component's root element.

Features

• ✅ All HTML5 elements supported
• ✅ Full ARIA attributes support
• ✅ Type-safe enum validation
• ✅ PreMount validation with OptionsResolver
• ✅ Proper namespace structure (Block/Inline/Void)

Components Structure

Components are organized by type:

• Block - Block-level elements (div, section, article, etc.)
• Inline - Inline elements (span, a, strong, etc.)
• Void - non-rendered elements (head, wbr, meta, etc.)

Read More

• Extended HTMLDocument Documentation
• Extended HTMLDocument Github Repository
• Twig Components
• Symfony UX

Issues & Bugs

Please report issues in this packages home at Extended HTMLDocument