react-native-formx

React Native FormX

⚛️ 📃 React Native custom form builder with support for plain form, tabs and step-by-step.

Native Dependencies

react-native-gesture-handler

react-native-reanimated

react-native-tab-view

Installation

npm i react-native-formx

react-native link react-native-gesture-handler
react-native link react-native-reanimated
react-native link react-native-tab-view

Examples

See examples/RNFormsPlayground for examples that you can play with.

Plain Form	Step by step	Tabs

Components

Name	Usage
Form	Form is the root component of the tree. It will render the internal form tree and will make avaiable the handlers for your component.
FormView	FormView is where all your fields will be really rendered. This is basically a View with all the fields(which are another components) rendered inside and some extra methods to handle internal submits/clears/validations events.
FormTabs	FormTabs is a manager for FormTab components.
FormTab	Imagine FormTab as a simple View rendered inside the FormTabs manager. Inside it will be displayed a FormView component where the fields will be rendered.
FormSteps	FormSteps is a amnager for FormStep components.
FormStep	Imagine FormStep as a simple View rendered inside the FormSteps manager. Inside it will be displayed a FormView component where the fields will be rendered. FormStep will contain specific step-by-step buttons like Back and Next Step.

Usage

Using components

import { Form } from 'react-native-formx';

const MyComponent = props => (
  <Form>
    /* Rendering as plain form */
    <FormView>
      {fields}
    </FormView>
    /* Rendering as tabs */
    <FormTabs>
      <FormTab title="Tab 1">
        {fields}
      </FormTab>
      <FormTab title="Tab 2">
        {fields}
      </FormTab>
    </FormTabs>
    /* Rendering as step-by-step */
    <FormSteps backButtonText="Go Back">
      <FormStep title="Step 1">
        {fields}
      </FormStep>
      <FormStep title="Step 2">
        {fields}
      </FormStep>
    </FormSteps>
  </Form>
);

Using props

You can render a form using only a .js configuration. In that cases the root Form component will automatically render based on props.

Plain form example

// withViewProps.js

const withViewProps = {
  fields: [
    //  list of fields
  ],
};

export default withViewProps;

Tabs example

// withTabProps.js

const withTabProps = {
  tabIndicatorColor: 'white',
  tabTintColor: 'purple',
  tabTextColor: 'white',
  tabs: [
    {
      title: 'Tab 1',
      fields: [
        //  list of fields
      ]
    },
    {
      title: 'Tab 2',
      fields: [
        //  list of fields
      ],
    },
  ],
};

export default withTabProps;

Step by step example

// withStepProps.js

const withStepProps = {
  indicatorColor: 'purple',
  buttonTintColor: 'purple',
  buttonTextColor: 'white',
  backButtonTextColor: 'purple',
  nextStepButtonText: 'Next Step',
  backButtonText: 'Go Back',
  steps: [
    {
      title: 'Step 1',
      fields: [
        // list of fields
      ],
    },
    {
      title: 'Step 2',
      fields: [
        // list of fields
      ],
    },
    {
      title: 'Step 3',
      fields: [
        // list of fields
      ],
    },
  ],
};

export default withStepProps;

then...

import { Form } from 'react-native-formx';
import withViewProps from './withViewProps';

const MyComponent = props => (
  <Form {...withViewProps} />
);

Methods

Name	Description	Support
submit	Manually submits the form. The form data will be avaiable on the onSubmit handler.	*
clear	Manually clears the form.	FormView, FormTabs

Handlers

Name	Description
onSubmit	Called after button of submit type pressed or manual call to submit public method.
onInvalid	Called when user tries to submit or request a new step and any of the active FormView fields have invalid values. The field payload will be defined as the first argument on this callback.

Example:

const handleSubmitForm = formData => console.log(formData);

const handleInvalidForm = field => {
  console.log(`Form "${field}" field got invalid value.`);
};

<Form
  {...props}
  onSubmit={handleSubmitForm}
  onInvalid={handleInvalidForm}
/>

Containers props

List of acceptable props for containers components.

FormStep

Name	Type
title	String
backButtonText	String
nextStepButtonText	String
buttonTintColor	Color
buttonTextColor	Color
submitButtonText	String

FormTabs

Name	Type
tabTintColor	Color
tabTextColor	Color
tabIndicatorColor	Color

Field types

Clear

Renders a clear button alongside the FormView content. This will automatically call the clear form method from inside it.

Prop	Type
title	String
buttonTintColor	Color
buttonTextColor	Color

Refers to this field using clear field type when rendering from props.

---

MaskedTextInput

Renders a react-native-text-input-mask text input component.

Prop	Type
name	String
title	String
maskType	String
validators	String

See react-native-text-input-mask for more avaiable props.

Refers to this field using masked field type when rendering from props.

---

Option

Renders a react-native-modal-select-list component.

Prop	Type
name	String
title	String
required	Boolean
options	Array[react-native-modal-select-list]

Refers to this field using option field type when rendering from props.

---

Radio

Renders a radio button with a list of options.

Prop	Type
name	String
title	String
options	Array[{ label: String, value: any }]

Refers to this field using radio field type when rendering from props.

---

Submit

Renders a submit button alongside the FormView content. This will automatically call the submit form method from inside it.

Prop	Type
title	String
buttonTintColor	Color
buttonTextColor	Color

Refers to this field using submit field type when rendering from props.

---

Switch

Renders a React Native Switch component.

Prop	Type
name	String
title	String
activeColor	Color

Refers to this field using switch field type when rendering from props.

---

TextInput

Renders a plain React Native TextInput component.

Prop	Type
title	String
name	String
required	Boolean
validators	String

Refers to this field using text field type when rendering from props.

---

Note: All the name are required at the runtime. This prop will be used to save the value from the form field inside the resumed form data object.

Dynamic fields

When using the form in step-by-step mode you can dynamically show some fields based on previous steps fields values. Declare a show function into the fields props. It will receive the actual formData within all inputed fields values until there. Return a boolean that tells if this field must be rendered and visible into the active FormView.

Example:

{
  name: 'myField',
  type: 'text',
  show: ({ anotherFieldValue }) => anotherFieldValue === 'abc',
}

Note: If field is not rendered by the FormView and user submit it will not be defined into the final submit form data.

Supported masks

There are some default supported masks that can be displayed when using MaskedTextInput with the default maskType prop.

See react-native-text-input-mask for reference.

Supported validators

You can use the following common validators as validator prop for TextInput and MaskedTextInput fields:

email, cpf, cnpj, phone, br-cellphone

Developed by

@ffrm - Fernando Rama