uniforms

<br>

<a href="https://coveralls.io/github/vazco/uniforms">
    <img src="https://img.shields.io/coveralls/vazco/uniforms.svg?maxAge=86400" alt="Coverage">
</a>

<a href="https://npmjs.org/package/uniforms">
    <img src="https://img.shields.io/npm/l/uniforms.svg?maxAge=86400" alt="License">
</a>

<a href="https://npmjs.org/package/uniforms">
    <img src="https://img.shields.io/npm/dm/uniforms.svg?maxAge=86400" alt="Downloads">
</a>

<a href="https://gitter.im/vazco/uniforms">
    <img src="https://img.shields.io/gitter/room/vazco/uniforms.svg?maxAge=86400" alt="Gitter">
</a>

<a href="https://npmjs.org/package/uniforms">
    <img src="https://img.shields.io/npm/v/uniforms.svg?maxAge=86400" alt="Version">
</a>

<a href="https://travis-ci.org/vazco/uniforms">
    <img src="https://img.shields.io/travis/vazco/uniforms.svg?maxAge=86400" alt="Status">
</a>

uniforms

In short: uniforms is a set of npm packages, which contains helpers and React components - both unstyled and themed with Bootstrap3, Bootstrap4 and Semantic UI - to easily manage, validate and even generate fully featured forms from your schemas.

Demo: uniforms.tools.

Installation

Note: If you are going to use a themed package - remember to include correct styles!

meteor

Note: If you prefer video, there's Meteor University uniforms session available here.

These are npm packages, so they can't imply any Meteor package, and you have to install dependencies manually. In your Meteor app directory:

# If you are going to use SimpleSchema
$ meteor add aldeed:simple-schema check

# If you are going to use SimpleSchema@2
$ meteor npm install simpl-schema

# If you are going to use GraphQL
$ meteor npm install graphql

# Components (pick one)
$ meteor npm install --save react react-dom uniforms uniforms-bootstrap3
$ meteor npm install --save react react-dom uniforms uniforms-bootstrap4
$ meteor npm install --save react react-dom uniforms uniforms-semantic
$ meteor npm install --save react react-dom uniforms uniforms-unstyled

npm

# Components (pick one)
$ npm install --save react react-dom uniforms uniforms-bootstrap3
$ npm install --save react react-dom uniforms uniforms-bootstrap4
$ npm install --save react react-dom uniforms uniforms-semantic
$ npm install --save react react-dom uniforms uniforms-unstyled

Quick start

Note: The following examples are designed to work out of box in meteor with SimpleSchema (a very common schema in meteor community), but it's not mandatory and you can easily use it without meteor and with different schemas (see: Custom Schema) There's also GraphQL support.

Let's start with defining an example schema:

import {SimpleSchema} from 'meteor/aldeed:simple-schema';

const PersonSchema = new SimpleSchema({
    name: {
        type: String,
        min: 3,
        max: 50
    },

    age: {
        type: Number,
        min: 0,
        max: 150
    }
});

const PostSchema = new SimpleSchema({
    category: {
        type: String,
        allowedValues: [
            "news",
            "image",
            "video"
        ]
    },

    authors: {
        type: [PersonSchema],
        minCount: 1,
        maxCount: 3
    },

    publishedDate: {
        type: Date
    },

    published: {
        type: Boolean,
        optional: true
    }
});

Then use it in your form:

// Remember to choose correct theme package
import AutoForm from 'uniforms-unstyled/AutoForm';

const PostCreateForm = () =>
    <AutoForm schema={PostSchema} onSubmit={doc => console.log(doc)} />
;

const PostUpdateForm = ({model}) =>
    <AutoForm schema={PostSchema} onSubmit={doc => console.log(doc)} model={model} />
;

That's all! AutoForm will generate complete a form with labelled fields, errors list (if any) and a submit button. Also, it will take care of validation and handle model changes.

Overview

Note: For a full description of components and their props - see API.

Forms components

Most of the time you'll be using either AutoForm or ValidatedForm, but there are also other form components (rather low-level ones) with different capabilities.

Component	Self-generated?	Self-managed?	Self-validated?
`AutoForm`	✔	✔	✔
`BaseForm`	✘	✘	✘
`QuickForm`	✔	✘	✘
`ValidatedForm`	✘	✘	✔
`ValidatedQuickForm`	✔	✘	✔

Fields components

This is a guaranteed set of fields - every theme package will implement these, but also can provide additional ones.

Component	Description
`AutoField`	Automatically renders given field.
`AutoFields`	Automatically renders given fields.
`BoolField`	Checkbox.
`DateField`	HTML5 `datetime-local` input.
`ErrorField`	Error message for given field.
`ErrorsField`	Error message with a list of validation errors.
`HiddenField`	Hidden field (with possibility to omit in DOM).
`ListAddField`	An icon with action to add list item.
`ListDelField`	An icon with action to remove list item.
`ListField`	List of nested fields.
`ListItemField`	Single list item wrapper.
`LongTextField`	Textarea.
`NestField`	Block of nested fields.
`NumField`	Numeric input.
`RadioField`	Radio checkbox.
`SelectField`	Select (or set of radio checkboxes).
`SubmitField`	Submit button.
`TextField`	Text (or any HTML5 compatible) input.

Advanced topics

Forms

Asynchronous validation

ValidatedForm (and so AutoForm) have an onValidate prop. It can be used to create an asynchronous validation:

const onValidate = (model, error, callback) => {
    // You can either ignore validation error...
    if (omitValidation(model)) {
        return callback(null);
    }

    // ... or any additional validation if an error is already there...
    if (error) {
        return callback();
    }

    // ... or feed it with another error.
    MyAPI.validate(model, error => callback(error || null));
};

// Later...

<ValidatedForm {...props} onValidate={onValidate} />

Autosave

Every form has an autosave functionality. If you set an autosave prop, then every change will trigger a submit. There's also an autosaveDelay prop - a minimum time between saves in milliseconds (default: 0).

Example:

<AutoForm
    autosave
    autosaveDelay={5000} // 5 seconds
    schema={schema}
    onSubmit={onSubmit}
/>

Hierarchy

Methods

You can use React ref prop to manually access form methods. Example usage:

const MyForm = ({schema, onSubmit}) => {
    let formRef;

    return (
        <section>
            <AutoForm ref={ref => formRef = ref} schema={schema} onSubmit={onSubmit} />
            <small onClick={() => formRef.reset()}>
                Reset
            </small>
            <small onClick={() => formRef.submit()}>
                Submit
            </small>
        </section>
    );
};

All available methods:

change(key, value)
reset()
submit()
validate() (added in ValidatedForm)

Model transformations

If you need to transform model before it will be validated, submitted or passed down to the fields, there's a modelTransform prop, which should be used in those use cases.

Example:

<AutoForm
    // Do not mutate given model!
    modelTransform={(mode, model) => {
        // This model will be passed to the fields.
        if (mode === 'form') {/* ... */}

        // This model will be submitted.
        if (mode === 'submit') {/* ... */}

        // This model will be validated.
        if (mode === 'validate') {/* ... */}

        // Otherwise, return unaltered model.
        return model;
    }}
    onSubmit={onSubmit}
    schema={schema}
/>

Post-submit handling

It's a good UX practice to tell your users, that something failed or succeed. To make it simpler, there are onSubmitFailure and onSubmitSuccess props.

Example:

<AutoForm
    schema={schema}
    onSubmit={doc => db.saveThatReturnsPromise(doc)}
    onSubmitSuccess={() => alert('Promise resolved!')}
    onSubmitFailure={() => alert('Promise rejected!')}
/>

Validation options and modes

Any form can be validated in one those three styles:

onChange Validate on every change.
onChangeAfterSubmit (default) Validate on every change, but only after first submit.
onSubmit Validate on every submit.

If your schema validator accepts any options, those can be passed in validator prop.

Example:

<AutoForm
    validate="onChange"
    validator={validatorOptions}
    schema={schema}
    onSubmit={onSubmit}
/>

Example: `ModifierForm`

import BaseForm from 'uniforms/BaseForm';

// In uniforms, every form is just an injectable set of functionalities. This
// way allows us to live without many higher order components in favour of
// composed one. If you want to get a deeper dive into it, read source of
// AutoForm or QuickForm in the core package.
const Modifier = parent => class extends parent {
    // Expose injector.
    //   It's not required, but recommended.
    static Modifier = Modifier;

    // Alter component display name.
    //   It's not required, but recommended.
    static displayName = `Modifier${parent.displayName}`;

    // Here you can override any form methods or create additional ones.
    getModel (mode) {
        if (mode === 'submit') {
            const doc  = super.getModel('submit');
            const keys = this.getChildContextSchema().getSubfields();

            const update = keys.filter(key => doc[key] !== undefined);
            const remove = keys.filter(key => doc[key] === undefined);

            // It's a good idea to omit empty modifiers.
            const $set   = update.reduce((acc, key) => ({...acc, [key]: doc[key]}), {});
            const $unset = remove.reduce((acc, key) => ({...acc, [key]: ''}), {});

            return {$set, $unset};
        }

        return super.getModel(mode);
    }
};

// Now we have to inject our functionality. This one is a ModifierForm. Use any
// form component you want.
export default Modifier(BaseForm);

Fields

`AutoField` algorithm

let component = props.component;
if (component === undefined) {
    if (props.allowedValues) {
        if (props.checkboxes && props.fieldType !== Array) {
            component = RadioField;
        } else {
            component = SelectField;
        }
    } else {
        switch (props.fieldType) {
            case Date:    component = DateField; break;
            case Array:   component = ListField; break;
            case Number:  component = NumField;  break;
            case Object:  component = NestField; break;
            case String:  component = TextField; break;
            case Boolean: component = BoolField; break;
        }

        invariant(component, 'Unsupported field type: %s', props.fieldType.toString());
    }
}

Guaranteed props

Note: These are not the only props, that field will receive - these are guaranteed for all fields created with connectField helper.

Name	Type	Description
`changed`	`bool`	Has field changed?
`disabled`	`bool`	Is field disabled?
`error`	`object`	Field scoped part of validation error.
`errorMessage`	`string`	Field scoped validation error message.
`field`	`object`	Field definition from schema.
`fields`	`arrayOf(string)`	Subfields names.
`fieldType`	`func`	Field type.
`findError`	`func(name)`	Request another field error.
`findField`	`func(name)`	Request another field field.
`findValue`	`func(name)`	Request another field value.
`id`	`string`	Field id - given or random.
`label`	`string`	Field label.
`name`	`string`	Field name.
`onChange`	`func(value, [name])`	Change field value.
`parent`	`object`	Parent field props.
`placeholder`	`string`	Field placeholder.
`value`	`any`	Field value.

Props propagation

Few props propagate in a very special way. These are label, placeholder and disabled.

Example:

<TextField />                    // default label | no      placeholder
<TextField label="Text" />       // custom  label | no      placeholder
<TextField label={false} />      // no      label | no      placeholder
<TextField placeholder />        // default label | default placeholder
<TextField placeholder="Text" /> // default label | custom  placeholder

<NestField label={null}> // null = no label, but children have their labels
    <TextField />
</NestField>

<NestField label={false}> // false = no label and their children have no labels
    <TextField />
</NestField>

<ListField name="authors" disabled>   // Additions are disabled...
    <ListItemField name="$" disabled> // deletion too...
        <NestField disabled={false}>  // but editing is not.
            <TextField name="name" />
            <NumField  name="age" />
        </NestField>
    </ListItemField>
</ListField>

Note: label, placeholder and disabled are cast to Boolean before being passed to nested fields.