Validation Action Creators

actions.setValidity(model, validity, [options])

Returns an action that, when handled by a formReducer, changes the .valid state of the field model in the form to true or false, based on the validity (see below). It will also set the .validity state of the field model to the validity.

It simultaneously sets the .errors on the field model to the inverse of the validity.

Arguments

• model (String): the model whose validity will be set
• validity (Boolean | Object): a boolean value or an object indicating which validation keys of the field model are valid.
• options (Object): an object containing options for the action creator:

Options

• .errors (Boolean): if true, the validity will be set for .errors instead of .validity on the field. This is equivalent to actions.setErrors().

Example

import { actions } from 'react-redux-form';

// somewhere with dispatch():
dispatch(actions.setValidity('user.email', true));

// email field:
// {
//   valid: true,
//   validity: true,
//   errors: false
// }

let val = 'testing123';

dispatch(actions.setValidity('user.password', {
  required: val && val.length,
  correct: val === 'hunter2'
}));

// password field:
// {
//   valid: false,
//   validity: { required: true, correct: false },
//   errors: { required: false, correct: true }
// }

Tips

• If you really want to set error messages instead, use actions.setValidity(model, errors, { errors: true }).
• Since arrays are objects, the validity argument can be an array. Only do this if your use case requires it.

actions.validate(model, validators)

Returns an action thunk that calculates the validity of the model based on the function/object validators. Then, the thunk dispatches actions.setValidity(model, validity).

A validator is a function that returns true if valid, and false if invalid.

Arguments

• model (String): the model whose validity will be calculated
• validators (Function | Object): a validator function or an object whose keys are validation keys (such as 'required') and values are validators.

Example

import { actions } from 'react-redux-form';
import { isEmail } from 'validator';

// assume user.email = "foo@gmail"

// somewhere with dispatch():
dispatch(actions.validate('user.email', isEmail));
// will dispatch actions.setValidity('user.email', false)

dispatch(actions.validate('user.email', {
  isEmail,
  available: (email) => email !== '[email protected]'
});
// will dispatch actions.setValidity('user.email', {
//  isEmail: false,
//  available: true
// });

actions.asyncSetValidity(model, asyncValidator)

Returns an action thunk that calculates the validity of the model based on the async function asyncValidator. That function dispatches actions.setValidity(model, validity) by calling done(validity).

Arguments

• model (String): the model whose validity will asynchronously be set
• asyncValidator(value, done) (Function): a function that is given two arguments:
  • value - the value of the model
  • done - the callback where the calculated validity is passed in as the argument.

Example

import { actions } from 'react-redux-form';

// async function
function isEmailAvailable(email, done) {
  fetch('...', { body: email })
    .then((response) => {
      done(response); // true or false
    });
}

// somewhere with dispatch():
dispatch(actions.asyncSetValidity('user.email', isEmailAvailable));
// => 1. will set .pending to true, then eventually...
// => 2. will set .validity to response and .pending to false

Tips

• This action is useful for general-purpose asynchronous validation using callbacks. If you are using promises, using actions.submit(model, promise) is a cleaner pattern.

actions.setErrors(model, errors)

Returns an action that, when handled by a formReducer, changes the .valid state of the field model in the form to true or false, based on the errors (see below). It will also set the .errors state of the field model to the errors.

It simultaneously sets the .validity on the field model to the inverse of the errors.

Arguments

• model (String): the model whose validity will be set
• errors (Boolean | Object | String): a truthy/falsey value or an object indicating which error keys of the field model are invalid.

Example

import { actions } from 'react-redux-form';

// somewhere with dispatch():
dispatch(actions.setErrors('user.email', true));

// email field:
// {
//   valid: false,
//   validity: false,
//   errors: true
// }

dispatch(actions.setErrors('user.email', 'So many errors!'));

// email field:
// {
//   valid: false,
//   validity: false,
//   errors: 'So many errors!'
// }

let val = 'testing123';

dispatch(actions.setErrors('user.password', {
  empty: !(val && val.length) && 'Password is required!',
  incorrect: val !== 'hunter2' && 'The password is wrong'
}));

// password field:
// {
//   valid: false,
//   errors: { empty: false, incorrect: 'The password is wrong' }
// }

Tips

• If you aren't hard-coding error messages, use actions.setValidity(model, validity) instead. It's a cleaner pattern.
• You can set errors to a boolean, object, array, string, etc. Remember: truthy values indicate errors in errors.

actions.validateErrors(model, errorValidators)

Returns an action thunk that calculates the errors of the model based on the function/object errorValidators. Then, the thunk dispatches actions.setErrors(model, errors).

An error validator is a function that returns true or a truthy value (such as a string) if invalid, and false if valid.

Arguments

• model (String): the model whose validity will be calculated
• errorValidators (Function | Object): an error validator or an object whose keys are error keys (such as 'incorrect') and values are error validators.

Example

import { actions } from 'react-redux-form';
import { isEmail } from 'validator';

// assume user.email = "foo@gmail"

// somewhere with dispatch():
dispatch(actions.validateErrors('user.email', (val) => {
  return !isEmail(val) && 'Not an email!'
}));
// will dispatch actions.setErrors('user.email', 'Not an email!')

dispatch(actions.validateErrors('user.email', {
  notAnEmail: (val) => !isEmail(val) && 'Not an email!',
  unavailable: (email) => email == '[email protected]' && 'Use a different email'
});
// will dispatch actions.setErrors('user.email', {
//  notAnEmail: 'Not an email!',
//  unavailable: false
// });

Tips

• As previously stated, if you aren't using error messages, use actions.validate(model, validators) as a cleaner pattern.

actions.submit(model, promise)

Waits for a submission promise to be completed, then, if successful:

• Sets .submitted property of form for model to true
• Sets .validity property of form for model to the response (or true if the response is undefined).

If the promise fails, the action will:

• set .submitFailed property of form for model to true
• set .errors property of form for model to the response

Arguments

• model (String): the model to be submitted
• promise (Promise): the promise that the submit action will wait to be resolved or rejected