FAQ

How can I customize/style my form fields?

You can style your form fields simply by passing a className property.

How can I create custom fields?

You can create a custom field by wrapping your component inside the connectField.

The connectField will pass various props related to the form management, such as onChange() function, current field's value, errors and so on, to your component.

Please visit the Tutorials > Creating a custom field tutorial to see how to create your own fields.

How can I use a custom field in my form?

You can tell your schema to use your custom field by adding the uniforms property.

Example in JSONSchema:

const schema = {
/*...*/
firstName: {
type: 'string',
uniforms: MyCustomFirstNameField
}
/*...*/
};

We say that the component used for the firstName property will be the MyCustomFirstNameField.

You can also leave the schema untouched and pass your custom field directly to the AutoField in a component property instead:

<AutoForm schema={schema} onSubmit={onSubmit}>
/*...*/
<AutoField component={MyCustomFirstNameField} name="firstName" />
/*...*/
</AutoForm>

How can I pass additional props to the custom field?

You can pass any additional props to your custom field, by converting the uniforms property to the type of object, with the component key. Any other keys will be treated as props.

E.g. in JSONSchema:

const schema = {
/*...*/
firstName: {
type: 'string',
uniforms: {
component: MyCustomFirstNameField,
propA: 1,
propB: 2
}
}
/*...*/
};

We say that the component used for the firstName property will be the MyCustomFirstNameField and it will receive 2 additonal props: propA and propB.

You can also leave the schema untouched and pass your custom field with props directly to the AutoField instead:

<AutoForm schema={schema} onSubmit={onSubmit}>
/*...*/
<AutoField
component={MyCustomFirstNameField}
name="firstName"
propA={1}
propB={2}
/>
/*...*/
</AutoForm>

How can I have a dynamic label? (e.g. handling i18n)

There are few ways to handle that, depending on the level of abstraction you want to do it - schema, field or AutoField component.

On the schema level, you can use uniforms: {...} object property to pass extra props to the field. A function returning it (uniforms: () => ({...})) is also accepted. With it, dynamic labels can be fetched from any source.

On the field level, you can prepare your own component set, where you will use <Translate>{label}</Translate> instead of {label}.

While the first one is schema-dependent and the second is theme-dependent, there's an additional option, somewhere in between. You can create a custom AutoField component, based on a builtin one, where you provide some additional props and label might be one of them (based on other props, like name or some schema field).

How can I change the way my form validates?

Any form can be validated in one of those three styles:

  • onChange Validate on every change.

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

  • onSubmit Validate on every submit.

You change the way your form validates by setting validate prop:

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

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

<AutoForm validator={validatorOptions} />

How can I reset my form state?

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

These methods are:

  • change(key, value)
  • reset()
  • submit()
  • validate() (added in ValidatedForm)
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>
);
};

You can find more about form methods here.

I want my form to be prefilled with data. How can I do that?

You can pass the initial data to the form by using the model prop.

The model is an object with {field: value} structure. It doesn't matter if it has a prototype or not, but keep in mind that in onSubmit or in onChangeModel you'll receive a plain object. If you treat form as an input, then this is a value.

How can I transform my model?

You should modelTransform. It is a function transforming one model into another. It's used in a few situations (called 'modes') described below.

Remember not to mutate a given model!

function transform(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;
}
<AutoForm modelTransform={transform} schema={schema} onSubmit={onSubmit} />;

How can I make my form autofocused?

You can take a reference to the field and manually trigger .focus():

<AutoField name="firstName" inputRef={field => field.focus()} />

How can I create a multi-step form?

What is a multi-step form? Well, one can imagine at least two completely separate definitions:

  1. A set of independent forms with a shared state. That's the easier one as it's always possible. Each step renders a separate form, with a different schema/validator/style and moves to the next one when submitted, accumulating submitted data.

    This handles not only multi-step forms but also forms wizards with a tree-like structure (i.e. next step bases on the answers). Optional steps (skip step 2 if age < 40) and contextual validation (field Y in step 2 has to be greater than the value of X in step 1) is also possible.

    But it gets even better - each step may use a different forms library! It makes no sense but is definitely possible - each form is independent, and the orchestration happens in the application.

  2. A single form displayed in parts. It is, of course, possible to implement it, but the number of all configurations and options is massive. But let's skip that and see where a bigger problem is: the validation. In 1. each step is validated separately (i.e. can have a separate schema). Here, we have only one schema, and the schema itself has to know that some fields were not yet visible.

    Let's make an example. The schema is very basic: { a: string, b: string } (TypeScript notation). Now, as both a and b are required, a valid model has to have both. If the first step will render only the a field (b is on the next page), it's impossible to validate the form. This leads to a situation where the schema (logic) depends on the steps (UI). On the other hand, the form could be validated only at the end. The UX of this solution is terrible though - imagine a there's an error ten pages back error!

We are not planning to provide any out-of-the-box support for multi-step forms as option 1. is most of the time the best. It's not only the cleanest but also less complicated as well as doesn't rely on any library.

How can I know a current form state?

A current form state is available in React context, accessible through useForm and useField(name) hooks.

The context data consists of various properties which can be found in here.

Example usage:
function SubmittingState() {
const uniforms = useForm();
return uniforms.submitting ? 'Submitting...' : null;
}
<AutoForm>
<SubmittingState />
</AutoForm>;

I want to disable a submit button until there is a difference between the current form state and my model. How can I do it?

Basically, you have to find out whether there is a difference between a current form state and your model, e.g. by calling lodash's isEqual function. Current form state can be accessed through the context (see How can I know a current form state?) and form model can be passed as an ordinary prop:

function DifferentSubmitField({ initialModel }) {
const { model } = useForm();
return <SubmitField disabled={isEqual(uniforms.model, initialModel)} />;
}
const ChangedForm = ({ model }) => (
<AutoForm model={model}>
<DifferentSubmitField initialModel={model} />
</AutoForm>
);