<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/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.

Table of Contents generated with DocToc

Installation
- meteor
- npm
Quick start
Overview
- Forms components
- Fields components
Advanced topics
API
Troubleshooting
Contributing
Copyright and License

Installation

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

meteor

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

# 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).

Let's start with defining an example schema:

import {SimpleSchema} from '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:

import {AutoForm} from 'uniforms-semantic'; // Remember to choose correct theme package

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 form with labeled fields, an errors list (if any) and a submit button. Also, it will take care of validation and handling model changes.

Overview

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

Forms components

Most of 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 `date-localtime` 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 - 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)

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

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';
import {AutoForm} from 'uniforms-semantic'; // Remember to choose correct theme package

// In uniforms, every form is just an injectable set of functionalities. This way
// allows us to live without many higher order components in favor 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 also not required, but recommended.
    static displayName = `Modifier${parent.displayName}`;

    // Here you can override any internal form methods or create additional ones.
    onSubmit (event) {
        // Prevent default form submission.
        // In this example, we are calling this.props.onSubmit directly, but
        // normally you can just call super.onSubmit(event) - it will handle
        // it by default.
        if (event) {
            event.preventDefault();
            event.stopPropagation();
        }

        if (this.props.onSubmit) {
            const doc  = this.getModel();
            const keys = this.getChildContextSchema().getSubfields();

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

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

                this.props.onSubmit({
                    ...update.length && {$set},
                    ...remove.length && {$unset}
                });
            }
        }
    }
};

// Now we have to inject our functionality.
// This one can be called a ModifierBaseForm.
export default Modifier(BaseForm);

// Every functionality have to be overriden independently. This might seem a
// little bit crazy, but we have to override BaseForm#onSubmit. If you are
// using for example Bootstrap3, then change AutoForm.Semantic to AutoForm.Bootstrap3.
// This one can be called AutoModifierForm.
export default AutoForm.Auto(AutoForm.Validated(AutoForm.Quick(AutoForm.Semantic(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 casted to Boolean before being passed to nested fields.