[RFC] Theme Support for Symfony UX Twig Components

[devnix]

Problem Statement

Currently, Symfony UX Twig Components don't support theme switching for different UI frameworks (Bootstrap, Tailwind, Bulma, etc.). Developers need to manually create separate components or use complex conditional logic within templates.

Proposed Solution

Warning

I've used the help of Claude AI to help me draft code suggestions, so bear in mind that these are not specific suggestions since I still don't have a deep understanding of Twig Components internals

1. Core Components

// src/Attribute/WithTheme.php
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class WithTheme
{
    public function __construct(
        public readonly string $name,
        public readonly int $priority = 0
    ) {}
}

// src/Theme/ComponentThemeRegistry.php
class ComponentThemeRegistry
{
    private array $themes = [];
    private ?string $activeTheme = null;
    
    public function registerTheme(string $name, array $components): void
    {
        $this->themes[$name] = $components;
    }
    
    public function setActiveTheme(string $theme): void
    {
        $this->activeTheme = $theme;
    }
    
    public function resolveComponent(string $componentName): string
    {
        if (!$this->activeTheme) {
            return $componentName;
        }
        
        return $this->themes[$this->activeTheme][$componentName] ?? $componentName;
    }
}

// src/Theme/ThemeAwareComponentRenderer.php
class ThemeAwareComponentRenderer extends ComponentRenderer
{
    public function __construct(
        private ComponentThemeRegistry $themeRegistry,
        // ... other dependencies
    ) {}
    
    public function createComponent(string $name, array $props = []): ComponentInterface
    {
        $themedName = $this->themeRegistry->resolveComponent($name);
        return parent::createComponent($themedName, $props);
    }
}

2. Twig Extensions

// src/Twig/ComponentThemeExtension.php
class ComponentThemeExtension extends AbstractExtension
{
    public function __construct(
        private ComponentThemeRegistry $themeRegistry
    ) {}
    
    public function getTokenParsers(): array
    {
        return [
            new ComponentThemeTokenParser(),
        ];
    }
    
    public function getFunctions(): array
    {
        return [
            new TwigFunction('component_theme', [$this->themeRegistry, 'setActiveTheme']),
            new TwigFunction('themed_component', [$this, 'renderThemedComponent']),
        ];
    }
}

// src/Twig/ComponentThemeTokenParser.php
class ComponentThemeTokenParser extends AbstractTokenParser
{
    public function parse(Token $token): Node
    {
        $lineno = $token->getLine();
        $stream = $this->parser->getStream();
        
        $theme = $stream->expect(Token::STRING_TYPE)->getValue();
        $stream->expect(Token::BLOCK_END_TYPE);
        
        $body = $this->parser->subparse([$this, 'decideBlockEnd'], true);
        $stream->expect(Token::BLOCK_END_TYPE);
        
        return new ComponentThemeNode($theme, $body, $lineno, $this->getTag());
    }
    
    public function getTag(): string
    {
        return 'component_theme';
    }
}

3. Configuration

# config/packages/twig_component.yaml
twig_component:
    themes:
        bootstrap_5:
            - 'components-theme/bootstrap_5'
        tailwind:
            - 'components-theme/tailwind'
    default_theme: 'bootstrap_5'
    # if it doesn't find a template, still search it in `defaults`

4. Usage Examples

{# Template-level theme switching #}
{% component_theme 'tailwind' %}
    {{ component('alert', {message: 'Hello'}) }}
    {{ component('button', {text: 'Submit'}) }}
{% endcomponent_theme %}

{# Function-based approach #}
{{ themed_component('alert', 'bootstrap_5', {message: 'Hello'}) }}

// Controller-level theme switching
#[WithTheme('bootstrap_5')]
class UserController extends AbstractController
{
    public function index(): Response
    {
        // All components in this action will use bootstrap_5 theme
        return $this->render('user/index.html.twig');
    }
}

// Runtime theme switching
class UserController extends AbstractController
{
    public function __construct(
        private ComponentThemeRegistry $themeRegistry
    ) {}
    
    public function profile(): Response
    {
        return $this->withComponentTheme('tailwind', function() {
            return $this->render('user/profile.html.twig');
        });
    }
}

Implementation Steps

Phase 1: Core Infrastructure

1. Create ComponentThemeRegistry service
2. Add WithTheme attribute
3. Modify component resolution logic
4. Add basic Twig functions

Phase 2: Template Integration

1. Implement {% component_theme %} tag
2. Add theme-aware component renderer
3. Create configuration system

Phase 3: Advanced Features

1. Theme inheritance
2. Component variants
3. Runtime switching helpers
4. Form theme integration

Phase 4: Developer Experience

1. Debug toolbar integration
2. Configuration validation
3. Performance optimizations
4. Documentation and examples

Backward Compatibility

• All existing components work without changes
• Theme system is opt-in
• No breaking changes to current APIs
• Graceful fallback when themes aren't configured

Migration Path

Existing projects can migrate gradually:

1. Install updated bundle
2. Configure themes (optional)
3. Start using theme features incrementally
4. Existing components continue working unchanged

Performance Considerations

• Theme resolution cached during request
• Minimal overhead when themes not used
• Component registry built once at container compile time
• No impact on existing non-themed components

---

I would be eager to try to do a prototype to gather how it should work and contribute with a pull request, I would love to have feedback from maintainers to check the viability and to steer the contribution to the right direction.

Thanks for this awesome package and community <3

[smnandre]

        // All components in this action will use bootstrap_5 theme
        return $this->render('user/index.html.twig');

Could you explain what this means ?

Where do the themes come from ? Are they only for components ? What about classic templates ? Would you create all your project component with several different themes ? Do you often need to change between Tailwind and Bootstrap at runtime ?

[devnix]

Hi @smnandre!

// All components in this action will use bootstrap_5 theme
return $this->render('user/index.html.twig');
Could you explain what this means ?

In the example

// Controller-level theme switching
#[WithTheme('bootstrap_5')]
class UserController extends AbstractController
{
    public function index(): Response
    {
        // All components in this action will use bootstrap_5 theme
        return $this->render('user/index.html.twig');
    }
}

the WithTheme attribute would set the ThemeAwareComponentRenderer to try to find a template in the specified folder, following the same conventions as if it would try to find it inside twig_component.defaults but in twig_component.themes.bootstrap_5 in this case, or fall back first to twig_component.default_theme and then to twig_component.defaults, showing warnings on the profiler as when you fall back on a translation.

Where do the themes come from ?

You would specify it in twig_component.themes, and templates would be found using the current convention, if no template is specified in the component (which is the current behavior).

Are they only for components ?

As I see it right now, yes. I would love to see something paired with the forms, but it would require a couple of modifications to the Form bridge. Right now, you can set several templates, and you choose if you want to render your forms with different styles, so that would force us to allow a traditional configuration to reach if no theme is specified

twig:
    form_themes: ['bootstrap_5_layout.html.twig']

and a more complex configuration

twig_components:
    form_themes: 
        bootstrap_5: ['bootstrap_5_layout.html.twig']
        tailwind: ['tailwind_2_layout.html.twig']

What about classic templates ?

I don't see much sense here. Classic templates act as a composition root for the different components, and they are usually already bound with a structure and a design. But if I'm working in a team and we are standardizing how to style a button, <twig:Atom:Button> or <twig:Molecule:SearchBar>, and a Storybook would help a lot in standardizing the UI and reducing boilerplate.

Additionally, different themes would require multiple entry points for CSS/JS to be defined at a root level.

I may be wrong and I'm wide open to suggestions, but I would easily find myself with a couple of examples:

# templates/sass/base.html.twig
{% component_theme 'sass' %}
{# ... #}

# templates/legacy_sass/base.html.twig
{% component_theme 'legacy_sass' %}
{# ... #}

# templates/website/base.html.twig
{% component_theme 'website' %}
{# ... #}

# templates/admin/base.html.twig
{% component_theme 'admin' %}
{# ... #}

Would you create all your project component with several different themes ?

In my specific case, I would iteratively do it, yes. At the time I would need to use a default button, I would write the component and add a couple of templates that I would need, having a default one defined in twig_component.default_theme. If a fallback is being used, the profiler could show a warning, and debug:twig-component could show warnings of all components missing a template in any theme:

+---------------+-----------------------------+------------------------------------+------+
| Component     | Class                       | Template                           | Type |
+---------------+-----------------------------+------------------------------------+------+
| Warning       | App\Components\Alert        | components/Coucou.html.twig        |      |
| RandomNumber  | App\Components\RandomNumber | components/RandomNumber.html.twig  | Live |
+---------------+-----------------------------+------------------------------------+------+

Theme: admin

+-----------+-----------------------+-----------------------------------------+------+
| Component | Class                 | Template                                | Type |
+-----------+-----------------------+-----------------------------------------+------+
| Button    | App\Components\Button | components-theme/admin/Button.html.twig |      |
| Alert     | App\Components\Alert  | components-theme/admin/Alert.html.twig  |      |
+-----------+-----------------------+-----------------------------------------+------+

Theme: website

+-----------+-----------------------+-------------------------------------------+------+
| Component | Class                 | Template                                  | Type |
+-----------+-----------------------+-------------------------------------------+------+
| Button    | App\Components\Button | components-theme/website/Button.html.twig |      |
| Alert     | App\Components\Alert  | !! MISSING !!                             |      |
+-----------+-----------------------+-------------------------------------------+------+

Do you often need to change between Tailwind and Bootstrap at runtime ?

Probably for rendering emails and stuff like that

[Kocal]

Hi, thanks for taking time to open this RFC, but I'm pretty sure this is definitely not something we want to integrate in TwigComponent, it requires too much code for a super-niche feature, and it can easily been handled app-side:

{# templates/components/Button.html.twig #} 
{% if theme == 'tailwind' %}
    <twig:Tailwind:Button {{ ...attributes }}>{% block content %}{% endblock %}</twig:Tailwind:Button>
{% else %}
    <twig:Tailwind:Bootstrap {{ ...attributes }}>{% block content %}{% endblock %}</twig:Tailwind:Bootstrap>
{% endif %}

However, I faced a similar issue while working documenting UX Toolkit on the website, I had to tweak the ComponentTemplateFinder to dynamically select a Component template files given a kit (like 'shadcn'), see https://github.com/symfony/ux/blob/2.x/src/Toolkit/src/Kit/KitContextRunner.php

[devnix]

That's a solution indeed, yet it still feels very cumbersome having to write a wrapper and conditionals for each component, but it is what it is 😅

Very interested in the ux-toolkit component, I didn't have an idea that something like that was in development! It feels like a very natural and important step to build full stack applications in Symfony, thank you 🙂

[devnix]

Hi, thanks for taking time to open this RFC, but I'm pretty sure this is definitely not something we want to integrate in TwigComponent, it requires too much code for a super-niche feature, and it can easily been handled app-side:

{# templates/components/Button.html.twig #} 
{% if theme == 'tailwind' %}
<twig:Tailwind:Button {{ ...attributes }}>{% block content %}{% endblock %}</twig:Tailwind:Button>
{% else %}
<twig:Tailwind:Bootstrap {{ ...attributes }}>{% block content %}{% endblock %}</twig:Tailwind:Bootstrap>
{% endif %}
However, I faced a similar issue while working documenting UX Toolkit on the website, I had to tweak the ComponentTemplateFinder to dynamically select a Component template files given a kit (like 'shadcn'), see https://github.com/symfony/ux/blob/2.x/src/Toolkit/src/Kit/KitContextRunner.php

Sorry to bother here, but I don't find a way to do this without having a theme attribute, which would kill the idea of having a if/else since I could directly do <twig:Button:Tailwind /> instead of <twig:Button theme=tailwind />.

I can set a global twig variable in twig.yaml but I don't find a single way to set it on a base.html.twig file and getting the new value in the component.

[Kocal]

Yeah I was thinking about a global Twig variable too.

For the second alternative, your needs reminds me #2522
Apparently using plain {% set %} tags could works to provide the theme across your components, but something more explicit like provide()/inject() (like suggested in #2522 (comment)) would be better.
In your case, I believe you can create a stateful Twig extension that provide two function set_theme() (call it in your base.html.twig) and get_theme() (call it in your components).

[devnix]

Apparently using plain {% set %} tags could works to provide the theme across your components

That's what I thought too, but it seems like setting a variable in a base template does not propagate the value to the components. Using outerScope.theme throws an Key "theme" does not exist as the sequence/mapping is empty error, so I'm out of ideas around using {% set %}.

I've been thinking too about a stateful plugin and functions to query the current theme, but that would probably get us to the initial proposal.

I'm going to check out that path, as I set a template name I will also want to change the default form themes (I didn't find a way to change them globally from templates and I want to pair both things)

[devnix]

Hi @Kocal ! I dont want to get very offtopic, but Im finding a big stone on this path: the theme variable is lost if a component is used in a live component.

The correct extension point would be to listen the PreMount event on the theme service, and if an internal "_theme" attribute is not set, fill it with the current loaded theme, and if it's set, load the theme? I have a weird feeling about rendering the attribute in the component, and I also think that there's a couple more of problems (I'm out of the computer right now)

[smnandre]

So here it's not that much a theme system than a dynamic template resolver. We will offer something in 3.1 something you can plug yourself on to do this.

But for now, as @Kocal said, this is really too niche to be integrated in the component.

Side note: it may seem easy/simple but, if you have time, you can look in the symfony/symfony repository past issues/PR why "trans_default_domain" or "form_theme" are not providing this kind of "statefullness" .. and the many many problems such implementation would need to solve first!

[FluffyDiscord]

I would also love this. My use case is similar. I am loading different Twig form themes for user section and administrative section. I cannot register both at the same time. I am detecting the current route, and adjusting ehich themes are loaded in Symfony, and my live components. The issue is that live components have their own route. Right now I am injecting current theme list as a live property, and extracting it using request listener, to apply them to that request, so my forms in live components don't suddenly break due to different theme/rendering. Having this built in would be extremely appreciated.