Symfony UX React

Edit this page

Symfony UX React is a Symfony bundle integrating React in Symfony applications. It is part of the Symfony UX initiative.

React is a JavaScript library for building user interfaces. Symfony UX React provides tools to render React components from Twig, handling rendering and data transfers.

You can see a live example of this integration on the Symfony UX React demo.

Symfony UX React supports React 18+.

Installation

Note

This package works best with Symfony Reprise (Vite or Rsbuild). To use it with Webpack Encore, see Using with Webpack Encore; to use it with AssetMapper, see Using with AssetMapper.

Note

Symfony Reprise support requires symfony/ux-react 3.4 and symfony/reprise 0.4.

Install the bundle using Composer and Symfony Flex:

1
$ composer require symfony/ux-react

The Flex recipe will automatically set things up for you, adding the code to load your React components inside assets/app.js.

You also need the React plugin for your bundler so it can compile JSX: @vitejs/plugin-react for Vite, or @rsbuild/plugin-react for Rsbuild.

That's it! Any files inside assets/react/controllers/ can now be rendered as React components.

Usage

Register components

The Flex recipe will have already added the registerReactControllerComponents() code to your assets/app.js file:

1
2
3
4
5
6
// assets/app.js
import { registerReactControllerComponents } from '@symfony/ux-react';

registerReactControllerComponents(
    import.meta.glob('./react/controllers/**/*.{jsx,tsx}', { eager: true })
);

This will load all React components located in the assets/react/controllers directory. These are known as React controller components: top-level components that are meant to be rendered from Twig. The eager: true option is required because UX React does not support lazy-loaded components.

Render in Twig

You can render any React controller component in your Twig templates, using the react_component() function.

For example:

1
2
3
4
5
6
// assets/react/controllers/Hello.jsx
import React from 'react';

export default function (props) {
    return <div>Hello {props.fullName}</div>;
}

Note

Ensure your module exports the controller as the export default. The default export is used when resolving components.

1
2
3
4
5
6
7
8
9
10
11
{# templates/home.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <div {{ react_component('Hello', { fullName: 'Fabien' }) }}>
        Loading... <i class="fas fa-cog fa-spin fa-3x"></i>
    </div>

    {# Component living in a subdirectory: "assets/react/controllers/Admin/OtherComponent" #}
    <div {{ react_component('Admin/OtherComponent') }}></div>
{% endblock %}

Permanent components

The controller responsible to render the React components can be configured to keep the React component mounted when the root element is removed from the DOM, using the permanent option.

This is particularly useful when the root element of a component is moved around in the DOM or is removed and immediately re-added to the DOM (e.g. when using Turbo and its `data-turbo-permanent` attribute).

1
2
3
4
5
6
7
{# templates/home.html.twig #}
{% extends 'base.html.twig' %}

{# The React component will stay mounted if the div is moved in the DOM #}
<div {{ react_component('Hello', {fullName: 'Fabien'}, {permanent: true}) }}>
     Loading...
</div>

Using with Webpack Encore

With Webpack Encore, register your components with Webpack's require.context() instead of import.meta.glob():

1
2
3
4
// assets/app.js
import { registerReactControllerComponents } from '@symfony/ux-react';

registerReactControllerComponents(require.context('./react/controllers', true, /\.(j|t)sx?$/));

The Flex recipe sets Encore up for you, adding .enableReactPreset() to your webpack.config.js file. You also need Babel's React preset:

1
2
$ npm install -D @babel/preset-react --force
$ npm run watch

Note

For more complex installation scenarios, you can install the JavaScript assets through the @symfony/ux-react npm package.

Using with AssetMapper

Because the JSX format isn't pure JavaScript, using this library with AssetMapper requires some extra steps.

  1. Compile your .jsx files to pure JavaScript files. This can be done by installing Babel and the @babel/preset-react preset. Example: https://github.com/symfony/ux.symfony.com/blob/main/assets/react/build/package.json
  2. Point this library at the "built" controllers directory that contains the final JavaScript files:
1
2
3
# config/packages/react.yaml
react:
    controllers_path: '%kernel.project_dir%/assets/build/react/controllers'

Also, inside of your .jsx files, when importing another component, use the .js extension:

1
2
// use PackageList.js even though the file is named PackageList.jsx
import PackageList from '../components/PackageList.js';

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version