Quickly build schema-based forms in React with uniforms

uniforms are React libraries for building form-based web UIs from every schema. A schema is a formal representation of data, data types, allowable values, default values, required values, etc. These web UIs are designed for accepting, modifying, and presenting data and are usually embedded within an application.

In this tutorial, we’ll demonstrate how you can use uniforms to efficiently build schema-based forms in React.

Why do you need uniforms?

Manually writing HTML templates and the logic for data binding is hard, especially in a relatively large application. Forms are even trickier because they usually involve functionalities that are more advanced than data binding, such as validation and submission.

uniforms eliminate the stress of writing templates and the JavaScript logic for data binding. They facilitates form rendering and take care of state management, validation, and submission.

Below are the core features of uniforms, according to the official documentation.

• Automatic forms generation
• Fields capable of rendering every schema
• Helper for creating custom fields with one line
• Inline and asynchronous form validation
• Various schemas integration
• Wide range of themes support

How do uniforms work?

uniforms are defined by the following.

1. Schema — Compatible schemas include GraphQL schema, JSON Schema, uniforms-bridge-simple-schema, and uniforms-bridge-simple-schema-2
2. Theme — The theme is a package that contains prestyled form components from any of today’s popular style libraries, such as AntDesign, Bootstrap 3, Bootstrap 4, Material Design, Semantic, unstyled HTML, etc.
3. Schema bridge — A bridge is a unified schema mapper that uniforms’ internals use to operate on the schema data, validate the form, and generate from errors. uniforms has a predefined schema-to-bridge mapper, uniforms-bridge-json-schema, that can be used to create a schema bridge

Using uniforms

Let’s say the marketing team at your company wants to collect lead information and you’ve agreed to help. Your task is to use uniforms to create a form for users to contact to the marketing team.

Installation

To use uniforms, you must first install the dependent packages. We’ll use JSON Schema to specify the data format, Bootstrap 4 as our UI theme, and Ajv for schema validation.

To install the required packages run the command below.

npm install uniforms uniforms-bridge-json-schema uniforms-bootstrap4 [email protected] ajv

Create a schema

Define the shape of the form by defining a plain JSON, which is a valid part of a JSON Schema.

// schema.js

const schema = {
  title: 'Lead Form',
  type: 'object',
  properties: {
    name: { type: 'string' },
    email: { type: 'string' },
    phone: {
      type: 'integer',
      minimum: 0,
      maximum: 100
    },
    reason: {
      type: 'string',
      options: [
        {
          label: 'Product Questions',
          value: 'product-questions'
        },
        {
          label: 'Online Order Support',
          value: 'online-order-support'
        },
        {
          label: 'Sales-support',
          value: 'sales-support'
        },
        {
          label: 'Events',
          value: 'events'
        }
      ]
    },
    message: {
      type: 'string',
      uniforms: {
        component: LongTextField
      }
    }
  },
  required: ['firstName', 'email', 'message']
};

Create a bridge

For uniforms to make use of any schema, you must create a bridge of the schemas.

The following schemas are compatible with uniforms.

• GraphQLBridge in uniforms-bridge-graphql
• JSONSchemaBridge in uniforms-bridge-json-schema
• SimpleSchema2Bridge in uniforms-bridge-simple-schema-2
• SimpleSchemaBridge in uniforms-bridge-simple-schema

import { JSONSchemaBridge } from 'uniforms-bridge-json-schema';

const bridge = new JSONSchemaBridge(schema);

Though JSON Schema is easy to use with uniforms, it doesn’t come with validation out of the box. You must manually define a validator to use on your contact form.

Let’s use Ajv for validation:

import Ajv from 'ajv';

const ajv = new Ajv({ allErrors: true, useDefaults: true });

function createValidator(schema) {
  const validator = ajv.compile(schema);

  return model => {
    validator(model);

    if (validator.errors && validator.errors.length) {
      throw { details: validator.errors };
    }
  };
}

const schemaValidator = createValidator(schema);

Now that you have a validator, you can include it as part of the bridge.

const bridge = new JSONSchemaBridge(schema, schemaValidator);

At this point, the schema.js file should look like this:

import Ajv from 'ajv';
import { JSONSchemaBridge } from 'uniforms-bridge-json-schema';
const ajv = new Ajv({ allErrors: true, useDefaults: true });
const schema = {
  title: 'Lead Form',
  type: 'object',
  properties: {
    name: { type: 'string' },
    email: { type: 'string' },
    phone: {
      type: 'integer',
      minimum: 0,
      maximum: 100
    },
    reason: {
      type: 'string',
      options: [
        {
          label: 'Product Questions',
          value: 'product-questions'
        },
        {
          label: 'Online Order Support',
          value: 'online-order-support'
        },
        {
          label: 'Sales-support',
          value: 'sales-support'
        },
        {
          label: 'Events',
          value: 'events'
        }
      ]
    },
    message: {
      type: 'string',
      uniforms: {
        component: LongTextField
      }
    }
  },
  required: ['firstName', 'email', 'message']
};

function createValidator(schema) {
  const validator = ajv.compile(schema);
  return model => {
    validator(model);
    if (validator.errors && validator.errors.length) {
      throw { details: validator.errors };
    }
  };
}
const schemaValidator = createValidator(schema);
const bridge = new JSONSchemaBridge(schema, schemaValidator);
export default bridge;

Add the schema to a form

Uniforms’ theme packages include a component called AutoForm that generates a form from the schema.

Pass the schema to AutoForm to generate a form.

import React from "react";
import "./styles.css";
import { AutoForm, AutoFields, ErrorsField, SubmitField } from 'uniforms-bootstrap4';

import LeadSchema from './schema';
export default function App() {
  return (
    <div className="App">
      <div className="uniforms">
        <AutoForm schema={LeadSchema} onSubmit={(e) => {console.log(e)}}>
          <h4>Have a question? Contact Sales</h4>
          <AutoFields />
          <ErrorsField />
          <SubmitField />
        </AutoForm>
      </div>
    </div>
  );
}

Conclusion

Now you have the basic knowledge you need to create schema-based forms in React using uniforms. The library comes with myriad other prebuilt form elements you can explore in the uniforms documentation.

The snippets used in this tutorial come from an example app. You’re welcome to clone it and play with it yourself.