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-antd
$ 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-material
$ 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-antd
$ 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-material
$ 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 the box in meteor with SimpleSchema (a very common schema in the 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 and JSON Schema support.

Let's start with defining an example schema:

// Choose your theme
import AutoForm from 'uniforms-unstyled/AutoForm';

// A compatible schema
import PostSchema from './schemas/Post';

// This will render an automatic, validated form, with labelled fields, inline
// validation and a submit button. If model will be present, form will be filled
// with appropriate values.
const PostForm = ({model}) =>
    <AutoForm schema={PostSchema} onSubmit={doc => db.save(doc)} model={model} />
;

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

If you want to have custom layout and/or structure inside your form you can include the form content.

// Choose your theme
import AutoField   from 'uniforms-unstyled/AutoField';
import AutoForm    from 'uniforms-unstyled/AutoForm';
import SubmitField from 'uniforms-unstyled/SubmitField';
import TextField   from 'uniforms-unstyled/TextField';

// A compatible schema
import PostSchema from './schemas/Post';

const PostForm = ({model}) =>
    <AutoForm schema={PostSchema} onSubmit={doc => db.save(doc)} model={model}>
        <h2>Title</h2>

        <AutoField name="fieldA" />
        <TextField name="fieldB" />

        <div className="super-special-class">
            <SubmitField className="super-special-class-with-suffix" />
        </div>
    </AutoForm>
;

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 a given field.
`AutoFields`	Automatically renders given fields.
`BoolField`	Checkbox.
`DateField`	HTML5 `datetime-local` input.
`ErrorField`	Error message for a 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 a list item.
`ListDelField`	An icon with action to remove a 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) has 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)

Change reactions

If you want to make one field to influence others, simply extend AutoForm and override onChange method.

Example:

class ChainForm extends AutoForm {
    onChange (key, value) {
        if (key === 'key_to_intercept') return;
        if (key === 'key_to_translate') return super.onChange('another_key', value);
        if (key === 'key_to_mutate') {
            super.onChange('another_key1', value * 2);
            super.onChange('another_key2', value / 2);
            return;
        }

        super.onChange(key, value);
    }
}

It can be easily applied multiple times to make your forms even more reusable.

Example:

const withMultipliedField = (fieldA, fieldB, Form) =>
class withMultipliedFieldForm extends Form {
    onChange (key, value) {
        // Multiply fieldA
        if (key === fieldA)
            super.onChange(fieldB, value + value);

        // Pass every change
        super.onChange(key, value);
    }
};

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. Thus,
// we can live without many higher order components, using composed ones
// instead. If you want to get a deeper dive into it, read the 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 a 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 the children have their labels
    <TextField />
</NestField>

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

<ListField name="authors" disabled>          // Additions are disabled...
    <ListItemField name="$" disabled>        // ...deletion too
        <NestField disabled={false} name=""> // ...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.