React Easy Form

A react component that allows to easily create forms. It is basically a wrapper around for react hook form that takes out the pain of registering and configuring components and validations. All components in the form are based on the material ui theme. In order to use a custom mui theme, just wrap your form in the mui theme provider.

The package is flexible: you can still register custom elements in the react hook form if you have more customized needs.

Getting started

Install the package

npm install @aeco-cloud/react-easy-form

If you want to integrate nicely with material-ui, do not forget to include the Roboto font and use the CssBaseline component.

Working example:

import {ReactEasyForm, Checkbox, DatePicker, Dropdown, Slider, TextField} from "@aeco-cloud/react-easy-form"

import React from "react";
import { useForm, SubmitHandler, SubmitErrorHandler } from "react-hook-form";
import { Container, Button } from "@material-ui/core";
import { isValid } from "date-fns";

const App = () => {
  const onSubmit: SubmitHandler<any> = (data) => {
    console.log("submitted");
    console.log(data);
  };
  const onError: SubmitErrorHandler<any> = (e) => {
    console.log("could not submit due to errors");
    console.log(e);
  };

  const form = useForm();

  return (
    <div className="App">
      <Container maxWidth="md">
        <ReactEasyForm form={form}>
          <Checkbox
            name="checkbox1"
            type="radio"
            values={[
              { value: "true", text: "Ja" },
              { value: "false", text: "Nee" },
            ]}
            validation={{
              required: "Deze vraag is verplicht",
            }}
          />
          <DatePicker
            name="myDatePicker"
            muiProps={{color:"secondary"}}
            validation={{
              validate: {
                couldNotBeParsed: (value: any) => isValid(value) || "not a valid date",
                isAfterToday: (value: Date) => {
                  return value > new Date() || "Date should be in the future";
                },
              },
            }}
          />
          <Dropdown
            name="myDropdown"
            values={[
              { value: "afrika", text: "🇿🇦" },
              { value: "usa", text: "🇺🇸" },
            ]}
            muiProps={{ variant: "outlined" }}
          />
          <Slider
            name="mySlider"
            muiProps={{
              color:"secondary",
              max: 100,
              step: 10,
              marks: [
                { value: 20, label: "a rather low value" },
                { value: 80, label: "a rather high value" },
              ],
            }}
            validation={{
              validate: {
                lessThanTwenty: (value: any) => parseInt(value) < 20 || "should be lower than 20",
              },
            }}
          />
          <TextField
            name="myTextField"
            validation={{ required: "Please fill in this question" }}
            muiProps={{ color: "secondary", fullWidth: false }}
          />
          <Button onClick={form.handleSubmit(onSubmit, onError)}>Submit</Button>
        </ReactEasyForm>
      </Container>
    </div>
  );
};

export default App;

Documentation

ReactEasyForm

The main component is the ReactEasyForm component. The component accepts the following props:

| props | required | description | | ----------- | ----------- |------------| | form | yes | the form which is a result of the useForm() hook from react-hook-form| |style | no | a styles object | |errorStyle | no | a styles object that will be injected into the div that wraps all error texts |

All components that are wrapped inside the ReactEasyForm component will have acces to the form, it's settings and validations

import ReactEasyForm from "@aeco-cloud/react-easy-form";
import { useForm} from "react-hook-form";
const form = useForm()

<ReactEasyForm form={form}>
  // the components that fill up the form
  // check out the documentation for all available components
  <Components>
  // in order to be able to submit the form you need to call the handleSubmit function somewhere
  <Button onClick={form.handleSubmit((data) => {console.log(data)})}>Submit</Button>;
</ReactEasyForm>

Components

The form is constructed from a combination of components.

Currently the following components are available:

• TextField
• Dropdown
• CheckBoxButton
• RadioButton
• Slider
• DatePicker

Refer to the documentation of each element type to see which props are available.

TextField

A basic input textfield. Can also be used as a numberField

| Prop | required |value | Description | | ----------|-|-|------------| |name|yes|string| The uniqe name of this input | |validation | no | react hook register options | validation rules| |muiProps| no | MUI text-field props | All props (except name) from the MUI text-field props are available.

Dropdown

A dropdown element

| Prop | required |value | Description | | ----------|-|-|------------| |name|yes|string| The uniqe name of this input | |defaultValue|no|string| The default value. Should be one of the name attributes that is provided in the values prop | |values|yes|{name:string, label:string}[]|The options for the dropdown. name refers to the name that is available when the form is submitted, label is the label that is shown to the user | |validation | no | react hook register options | validation rules| |muiProps| no | MUI select props | All props (except name) from the MUI select props are available|

CheckboxButton

A fancy and customizable checkbox selection component to show a number of options from which a user can make a selection. This component is a combination of a button and a checkbox. By choosing different combinations for the buttonActiveMuiProps, buttonInactiveMuiProps, checkboxActiveMuiProps and checkboxInactiveMuiProps you can create many different UI components.

| Props | required |value | Description | | ----------|-|-|------------| |indicator | no | boolean | Set to true to show a checkbox indicator in the button. Default is true. |values| yes | {name:string, label:string}[] | The list of options to pick from. name refers to the value that is available when the form is submitted, label is the label that is shown to the user | |name|yes|string|The uniqe name of this input | |defaultValues|no|string[]| The default values. Should be one or more of the name attributes that is provided in the values prop | |buttonActiveMuiProps | no | MUI button props | The button props for the button in the active state| |buttonInactiveMuiProps | no | MUI button props | The button props for the button in the inactive state| |checkboxActiveMuiProps | no | MUI checkbox props | The checkbox props for the checkbox in the active state| |checkboxInactiveMuiProps | no | MUI checkbox props | The checkbox props for the checkbox in the inactive state| |validation | no | react hook register options | validation rules| |numberOfColumns | no | number | The number of columns to display. Default is 1. | |columnGap | no | number | The gap between the columns. Unit is px, default is 0. | |rowGap | no | number | The gap between the rows. Unit is px, default is 0. |

RadioButton

Equivalent to CheckboxButton. Only difference is that here a round box is shown to indicate that it is a radio button and the answers are mutually exclusive. All props are the same as on CheckboxButton except the following props:

| Props | required |value | Description | | ----------|-|-|------------| |defaultValue|no|string| The default value. Should be one of the name attributes that is provided in the values prop | |radioActiveMuiProps | no | MUI radio props | The radio props for the radio in the active state| |radioInactiveMuiProps | no | MUI radio props | The radio props for the radio in the inactive state|

Slider

A slider element.

| Props | required |value | Description | | ----------|-|-|------------| |name|yes|string|The uniqe name of this input | |defaultValue|no | number | [number,number] | the default value. if a list of two numbers is provided, a slider with a start and endpoint is created.| |validation | no | react hook register options | validation rules| |muiProps| no | MUI slider props | All props (except name and defaultValue) from the MUI slider props are available

DatePicker

A date picker element

| Parameter | required |value | Description | | ----------|-|-|------------| |name|yes|string|The uniqe name of this input | |defaultValue|no | Date | the default value. If this is not provided, the current date will be used.| |validation | no | react hook register options | validation rules| |muiProps|no| KeyboardDatePicker props | All props (except name, defaultValue, invalidDateMessage, minDateMessage and maxDateMessage) from the KeyboardDatePicker props. The invalidDateMessage, minDateMessage and maxDateMessage should be implemented as validations in the validation prop.

Roadmap

• Bugfix: on first render of checkboxButton/radioButton, the active style of default components is not applied => Done
• add search option to dropdown
• add example of validations in the documentation
• add data structure of submitted fields in the documentation
• add typed muiProps in the datePicker component
• document expected values on no input (undefined?) and after input

New Roadmap

• go over all components to see if they are implemented in the same way with RHF 7
• Clean the helpers (Question, section, label)
• Add the helpers to the library
• Add helpers to include icons and tooltips in the select buttons
• Use the Higher-order component api to have seperate stylesheets for each components.
• By using the higher-order component api it might be possible to use selectButtons by styling checkbox/radio without having to use the muiButton

Documentation Roadmap

• Question
• Section
• Label
• CheckboxButton
• RadioButton

changelog

• 0.2.0 => breaking changes: settings from the formConfig are now accessed as props
• 0.3.0 => breaking changes: formConfig is deprecated, components are now submitted as children of ReactEasyForm
• 0.4.0 => breaking changes: muiProps are now supported in standard mui elements
• 0.4.1 => required props fixes
• 0.4.2 => style is now available as prop on the ReactEasyForm component
• 0.5.0 => breaking changes: CheckboxButton and RadioButton are now available and constructed with native mui components
• 0.5.2 => added styling helpers such as Section, Question and Label
• 0.5.3 => if question is not shown, it is removed from the DOM (otherwise you can have hidden fields that need validations)
• 0.6.0 => breaking changes: components have more predictable behaviour (no value = undefined) and renamings
• 0.6.1 => no value = "" (empty string) => this avoids errors about switching from controlled to uncontrolled
• 0.6.12 => added GROUP options in dropdown
• 0.7.0 => migrated to react hook from 7, needs more testing! Only use this version if you know what you are doing
• 0.7.1 => BUGFIX: on first render of checkboxButton/radioButton, the active style of default components is now applied