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.
- Schema — Compatible schemas include GraphQL schema, JSON Schema,
uniforms-bridge-simple-schema
, anduniforms-bridge-simple-schema-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.
- 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
inuniforms-bridge-graphql
JSONSchemaBridge
inuniforms-bridge-json-schema
SimpleSchema2Bridge
inuniforms-bridge-simple-schema-2
SimpleSchemaBridge
inuniforms-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.
Get setup with LogRocket's modern React error tracking in minutes:
- Visit https://logrocket.com/signup/ to get an app ID.
- Install LogRocket via NPM or script tag.
LogRocket.init()
must be called client-side, not server-side. - (Optional) Install plugins for deeper integrations with your stack:
- Redux middleware
- ngrx middleware
- Vuex plugin
$ npm i --save logrocket
// Code:
import LogRocket from 'logrocket';
LogRocket.init('app/id');
Add to your HTML:
<script src="https://cdn.lr-ingest.com/LogRocket.min.js"></script>
<script>window.LogRocket && window.LogRocket.init('app/id');</script>