Skip to content

Latest commit

 

History

History
160 lines (107 loc) · 5.13 KB

index.rst

File metadata and controls

160 lines (107 loc) · 5.13 KB

Symfony UX React

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

Make sure you have WebpackEncore if you are not working with AssetMapper. You can install and configure Webpack Encore through the Symfony Encore bundle. This will modify your base.html.twig template and create assets/app.js, in addition to adding and modifying other configuration, which will in turn help you get started faster with the UX React bundle.

Note

This package works best with WebpackEncore. To use it with AssetMapper, see :ref:`Using with AssetMapper <using-with-asset-mapper>`.

Install the bundle using Composer and Symfony Flex:

$ composer require symfony/ux-react

The Flex recipe will automatically set things up for you, like adding .enableReactPreset() to your webpack.config.js file and adding code to load your React components inside assets/app.js.

Next, install a package to help React:

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

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:

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

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

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.

Render in Twig

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

For example:

// assets/react/controllers/Hello.jsx
import React from 'react';

export default function (props) {
    return <div>Hello {props.fullName}</div>;
}
{# 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

.. versionadded:: 2.21

    The ability to mark a component ``permanent`` was added in UX React 2.21.

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).

{# 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 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/blob/2.x/ux.symfony.com/assets/react/build/package.json
  2. Point this library at the "built" controllers directory that contains the final JavaScript files:
# 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:

// 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