February 1, 2025

A Simple and Efficient Frontend with Twig Components and Tailwind CSS

Symfony, with Twig for templating, remains a staple in the PHP ecosystem, while Tailwind CSS has established itself as a leading CSS framework. Together, these tools offer interesting synergies to modernize your frontend.

Why Combine Tailwind CSS and Twig Components?

Symfony is known as a solid backend framework, and its frontend ecosystem has evolved significantly. With the Symfony UX suite, the framework now offers interesting approaches for frontend development.

Twig, the template engine, has its pros and cons like any template engine, but it remains a solid choice for structuring your views. Additionally, Tailwind CSS allows for quick and consistent styling with its utility classes.

Twig Components are introduced to encourage reusability and clarity in views and can integrate seamlessly with Tailwind CSS. Tailwind, by allowing styles to be declared directly in the DOM, facilitates the quick styling of Twig components.

By combining the two, you can encapsulate both the structure and UI of a component. Moreover, with class components, you can also encapsulate the component's behavior. Thus, you can reuse everything at will in your application to gain productivity and consistency.

Quick Overview of the Tools

Before exploring their synergies, here is a reminder of the main features of each tool:

Twig Components

Twig Components are an evolution brought in Symfony UX, allowing you to structure your templates into reusable components.

Anonymous Components: simple and without logic, just a Twig template.
Class Components: for more complex components, with methods and properties. A PHP class associated with a Twig template.
There are also Live Components, which allow for dynamic DOM updates. If you want to know more, I invite you to check out Symfony UX Live Components Documentation

Tailwind CSS

Tailwind CSS is a utility-first CSS framework. Unlike traditional CSS frameworks (like Bootstrap), it favors the use of utility classes that allow for quick and limitless styling. It is particularly appreciated for its flexibility and ecosystem.

Fully customizable through its tailwind.config.js configuration file for v3 or a simple CSS file for v4, Tailwind CSS allows you to customize colors, sizes, fonts, etc. A good configuration is an asset for effective use of Tailwind.

Synergies between Twig Components and Tailwind CSS

Anonymous Components

Let's take a simple example, a button with color and size variants.
There is an approach called CVA (Class Variant Authority), which centralizes the management of conditional CSS classes, making your components modular, easy to evolve, and maintain. Initially popularized in the JavaScript world, it is now available in Twig!

templates/components/button.html.twig

{% props as = 'button', variant = 'default', size = 'default' %}

{% set buttonVariants = cva({
    base: 'inline-flex items-center justify-center gap-2 w-fit whitespace-nowrap rounded-md text-sm font-medium transition-colors',
    variants: {
        variant: {
            default: 'bg-primary text-primary-foreground hover:bg-primary/90',
            secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        },
        size: {
            default: 'h-10 px-4 py-2',
            lg: 'h-12 rounded-md px-8',
        }
    },
    defaultVariants: {
        variant: 'default',
        size: 'default',
    }
}) %}

<{{ as }} {{ attributes.without('class') }}
    class="{{ buttonVariants.apply({variant, size}, attributes.render('class'))|tailwind_merge }}"
>
    {% block content '' %}
</{{ as }}>

Here is our button component that accepts three props: as, variant, and size. This "polymorphic" component approach allows the component to default to a button tag, but you can change it to a, or another HTML tag by passing the desired tag via the as prop.

Usage

<twig:button as="a" href="https://knplabs.com" size="lg">Discover KNPlabs</twig:button>

HTML Output

<a href="https://knplabs.com" class="inline-flex items-center justify-center gap-2 w-fit whitespace-nowrap rounded-md text-sm font-medium transition-colors bg-primary text-primary-foreground hover:bg-primary/90 h-12 px-8">
    Discover KNPlabs
</a>

Find another usage example for headings on our demo repo

Bonus `tailwind_merge`

Note here the use of the tailwind_merge filter which merges duplicate or conflicting Tailwind classes when you override your component's classes.

<twig:button as="a" href="https://knplabs.com" size="lg" class="bg-red-500">Red KNPlabs</twig:button>

HTML Output:

<a href="https://knplabs.com" class="inline-flex items-center justify-center gap-2 w-fit whitespace-nowrap rounded-md text-sm font-medium transition-colors h-12 px-8 bg-red-500">
    Red KNPlabs
</a>

Instead of having conflicting classes like bg-primary and bg-red-500, the tailwind_merge filter merges duplicate classes to keep only bg-red-500, as this class overrides bg-primary. The result is a red button.

Filter from the bundle tales-from-a-dev/twig-tailwind-extra: 🌱 A Twig extension for Tailwind

Class Components

You can also create components with PHP classes for more complex cases requiring some logic.

Let's take a simple example of formatting a price. Imagine your controller returns a price, and you want to display it in euros. For example, 1234 (prices are stored in cents) should be displayed as 12.34 €.

You can create a Twig Component with a PHP class and a template to handle the rendering. This component will accept price and locale properties and expose a formatPrice method.

src/Twig/Components/Price.php

<?php

namespace App\Twig\Components;

use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
use NumberFormatter;

#[AsTwigComponent('product:price')]
final class Price
{
    public int $price;
    public string $locale = 'fr_FR';

    public function formatPrice(): string
    {
        $formatter = new NumberFormatter($this->locale, NumberFormatter::CURRENCY);
        return $formatter->formatCurrency($this->price / 100, 'EUR');
    }
}

In this example, the attribute #[AsTwigComponent('product:price')] defines the component's name, which will be automatically linked to the templates/components/product/price.html.twig file. Here is what the Twig template styled with Tailwind might look like:

price.html.twig

<span {{ attributes.without('class') }}
    class="w-fit bg-gray-300 rounded-full px-3 py-1 text-sm font-semibold text-gray-900 {{ attributes.render('class')|tailwind_merge }}"
>
    {{ this.formatPrice }}
</span>

In this template, the formatPrice method is called via this.formatPrice.

Usage

<twig:product:price price="1234" />

HTML Output

<span class="w-fit px-3 py-1 bg-gray-300 rounded-full text-sm font-semibold text-gray-900">
    12.34 €
</span>

Bonus: Test Your Components

You can test your Twig components with PHPUnit with remarkable ease. Here is an example test for our Price component.

tests/Twig/Components/PriceTest.php

<?php

namespace App\Tests\Twig\Components;

use App\Twig\Components\Price;
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Symfony\UX\TwigComponent\Test\InteractsWithTwigComponents;

class PriceTest extends KernelTestCase
{
    use InteractsWithTwigComponents;

    public function testComponentMount(): void
    {
        $component = $this->mountTwigComponent(
            name: Price::class,
            data: ['price' => 9999, 'locale' => 'fr_FR'],
        );

        $this->assertInstanceOf(Price::class, $component);
        $this->assertSame(9999, $component->price);
        $this->assertSame('fr_FR', $component->locale);
    }

    public function testComponentRenders(): void
    {
        $rendered = $this->renderTwigComponent(
            name: Price::class,
            data: ['price' => 9999, 'locale' => 'fr_FR'],
        );

        $this->assertStringContainsString('99.99 €', $rendered);
    }
}

And that's it, nothing more complicated than that to test your Twig components. We test the component's mounting and rendering, quite simply.

Limitations

Code Readability
The abundance of Tailwind classes in a single file can make large templates difficult to read. A good knowledge of Tailwind utilities is necessary to maintain good readability. Additionally, Twig Components introduce a new syntax that can be a bit confusing at first but remains very close to HTML.
Learning Curve
Although Tailwind is easy to use, its utility-first logic can confuse developers accustomed to traditional CSS approaches. Tailwind remains relatively simple to learn, and the documentation is very well done.

Conclusion

Combining Twig Components and Tailwind CSS can greatly modernize your frontend development workflow with Symfony. These tools complement each other perfectly: Twig provides modular structure, while Tailwind accelerates styling.

However, their use requires good organization and an understanding of the limitations to fully leverage their synergies. This combination is particularly suitable for teams looking for a modern and modular approach, somewhat like React components.

For the curious, you can find an example of this stack on our demo repo.

erwannrousseau.dev

erwannrousseau.dev

A Simple and Efficient Frontend with Twig Components and Tailwind CSS

Why Combine Tailwind CSS and Twig Components?

Quick Overview of the Tools

Twig Components

Tailwind CSS

Synergies between Twig Components and Tailwind CSS

Anonymous Components

Usage

HTML Output

Bonus `tailwind_merge`

Class Components

Usage

HTML Output

Bonus: Test Your Components

Limitations

Conclusion

A Simple and Efficient Frontend with Twig Components and Tailwind CSS

Why Combine Tailwind CSS and Twig Components?

Quick Overview of the Tools

Twig Components

Tailwind CSS

Synergies between Twig Components and Tailwind CSS

Anonymous Components

Usage

HTML Output

Bonus tailwind_merge

Class Components

Usage

HTML Output

Bonus: Test Your Components

Limitations

Conclusion

Bonus `tailwind_merge`