react-symfony-form

Symfony forms built with React

This package is designed to be used in conjunction with the Symfony bundle ReactSymfonyFormBundle found at https://github.com/stephen-lewis/react-symfony-form-bundle.

The Symfony bundle converts the Symfony Forms FormView object into a JSON object that this package can understand. A collection of React components then allow the form to be rendered easily, just as with Twig. For consistency, the React components are named in a similar fashion to the equivalent Twig function (e.g. <FormRow/> ~ form_row()).

These components can then be extended to use custom validation or otherwise integrate with an existing or new React app.

Installation

Within a Symfony app, install the package using yarn (or npm).

yarn install react-symfony-form

Usage

The package exposes its components and some helper functions in the usual way.

import { renderForm, Form, FormRow } from 'react-symfony-form';

renderForm()

This command is designed to work with the react_form_tag Twig function provided by react-symfony-form-bundle. It takes the normalized form view object and passes it to a React component. The component is then rendered at the location of the Twig tag. If no component is passed to renderForm then the Form component from this package is used.

import { renderForm } from 'react-symfony-form';
 
// {{ react_form_tag(userForm, 'user-form') }} used in Twig template where the 'userForm' needs to be rendered
 
renderForm('user-form'); // renders a <Form /> component
 
renderForm('user-form', MyUserFormComponent); // renders a customised React component

If a custom component is used, the form view object is passed on the formView prop.

<Form> Component

If self-closed it renders the HTML of a complete form.

<Form formView={form} />

If you need more flexibility in rendering the form, you should use the other helpers to render individual parts of the form instead:

<Form formView={form}>
    <FormErrors formView={form} />
    
    <FormRow formView={form.child(name)} />
    <FormRow formView={form.child(dueDate)} />
    
    <FormRow formView={form.child(submit)} vars={{label: 'Submit me'}} />
</Form>

The component fulfills a similar function to the form_start() and form_end() functions in Twig. The attributes allow overrides to variables assigned to the Symfony FormView object. As with Twig's form_end() function, adding the renderRest attribute with the value false will prevent the rendering of any unrendered child fields.

<Form formView={form} renderRest={false}>
    ... 
</Form>

<FormLabel> Component

Renders the label for the given field. You can optionally pass the specific label you want to display as the tag content.

<FormLabel formView={form.child(name)} />
 
// The two following syntaxes are equivalent (note use of 'className' rather than 'class')
<FormLabel formView={form.child(name)} labelAttr={'className': 'foo'}>Your Name</FormLabel>
 
<FormLabel formView={form.child(name)} label='Your Name' labelAttr={'className': 'foo'} />

<FormErrors> Component

Renders any errors for the given field.

<FormErrors formView={form.child(name)} />
 
// render any "global" errors
<FormErrors formView={formView} />

<FormWidget> Component

Renders the HTML widget of a given field. If you apply this to an entire form or collection of fields, each underlying form row will be rendered.

// render a widget, but add a "foo" class to it
<FormWidget formView={form.child(name)} attr={{className: 'foo'}} />

The <FormWidget> component accepts a number of attributes. The most common is attr, which is an object of HTML attributes to apply to the HTML widget. In some cases, certain types also have other template-related options that can be passed. These are discussed on a type-by-type basis. The attributes are not applied recursively to child fields if you're rendering many fields at once (e.g. <FormWidget formView={form}>).

<FormRow> Component

Renders the "row" of a given field, which is the combination of the field's label, errors and widget.

// render a field row, but display a label with text "foo"
<FormRow formView={form.child(name)} label='foo' />

The <FormRow> component accepts a number of attributes. The templates provided in this package currently only allow to override the label as shown in the example above (as is the case with the templates provided with Symfony).