Formsets API


class BaseFormSet([kwargs])

A collection of instances of the same Form.

  • kwargs (Object) – configuration options.
  • (Array.<Object>) – list of input form data for each form, where property names are field names. A formset with data is considered to be “bound” and ready for use validating and coercing the given data.
  • kwargs.files (Array.<Object>) – list of input file data for each form.
  • kwargs.autoId (String) – a template for use when automatically generating id attributes for fields, which should contain a {name} placeholder for the field name. Defaults to id_{name}.
  • kwargs.prefix (String) – a prefix to be applied to the name of each field in each form instance.
  • kwargs.onChange (Function) –

    A callback to indicate to the a React component that the formset has changed, e.g. when another form is added to the formset.

    This will be passed as the Form constructor’s onChange argument when creating the formset’s forms.

    New in version 0.9: Replaces kwargs.onStateChange

  • kwargs.initial (Array.<Object>) – a list of initial form data objects, where property names are field names – if a field’s value is not specified in data, these values will be used when rendering field widgets.
  • kwargs.errorConstructor (Function) – the constructor function to be used when creating error details - defaults to ErrorList().
  • kwargs.validation (Function) –

    A value to be passed as the Form constructor’s validation argument when creating the formset’s forms – defaults to null.

    New in version 0.6.

  • kwargs.managementFormCssClass (String) – a CSS class to be applied when rendering BaseFormSet#managementForm(), as default rendering methods place its hidden fields in an additonal form row just for hidden fields, to ensure valid markup is generated.

Instance Properties

Formset options documented in kwargs above are set as instance properties.

The following instance properties are also available:


Determines if this formset has been given input data which can be validated, or if it will display as blank or with configured initial values the first time it’s redered.

false if the formset was instantiated with or kwargs.files, true otherwise.

Prototype Functions

Prototype functions for retrieving forms and information about forms which will be displayed.


Creates and returns the ManagementForm instance for this formset.

A ManagementForm contains hidden fields which are used to keep track of how many form instances are displayed on the page.

On the browser, ManagementForms will only ever contain initial data reflecting the formset’s own configuration properties.

Determines the number of form instances this formset contains, based on either submitted management data or initial configuration, as appropriate.

On the browser, only the formset’s own form count configuration will be consulted.

Determines the number of initial form instances this formset contains, based on either submitted management data or initial configuration, as appropriate.

On the browser, only the formset’s own form count configuration will be consulted.

Returns a list of this formset’s form instances.


Increments formset.extra and adds another form to the formset.


Decrements formset.extra and removes the form at the specified index from the formset.

You must ensure the UI never lets the user remove anything but extra forms.

New in version 0.9.


Returns a list of all the initial forms in this formset.


Returns a list of all the extra forms in this formset.


Creates an empty version of one of this formset’s forms which uses a placeholder '__prefix__' prefix – this is intended for cloning on the client to add more forms when newforms is only being used on the server.

Prototype functions for validating and getting information about the results of validation, and for retrieving forms based on submitted data:

BaseFormSet#validate([form[, callback(err, isValid, cleanedData)]])

Forces the formset to revalidate from scratch. If a <form> is given, data from it will be set on the formset’s forms. Otherwise, validation will be done with each form’s current input data.

  • form – a <form> DOM node – if React’s representation of the <form> is given, its getDOMNode() function will be called to get the real DOM node.
  • Boolean, Object) callback (function(Error,) –

    Callback for asynchronous validation.

    This argument is required if the formdet or its form uses asynchronous validation - an Error will be thrown if it’s not given in this case.

    The callback should be an errback with the signature (err, isValid, cleanedData).


true if the formset’s forms’ data is valid, false otherwise.

New in version 0.9.

Changed in version 0.10: Added callback argument for async validation.


Updates the formset’s (and formset.isInitialRender, if necessary) and triggers form cleaning and validation, returning the result of formset.isValid().

  • data (Object) – new input data for the formset.

true if the formset has no errors after validating the updated data, false otherwise.

New in version 0.5.


Alias for BaseFormSet#setData(), to keep the FormSet API consistent with the Form API.

New in version 0.6.


Returns a list of form.cleanedData objects for every form in BaseFormSet#forms().

Changed in version 0.9: No longer returns cleaned data for extra forms which haven’t been modified.

Changed in version 0.10: No longer includes cleaned data from incomplete extra forms.


Returns a list of forms that have been marked for deletion.


Returns a list of forms in the order specified by the incoming data.

Throws an Error if ordering is not allowed.


Adds an error that isn’t associated with a particular form.

The error argument can be a simple string, or an instance of ValidationError().

New in version 0.9.


Returns an ErrorList() of errors that aren’t associated with a particular form – i.e., from BaseFormSet#clean() or externally via BaseFormSet#addError().

Returns an empty ErrorList() if there are none.


Returns a list of form error for every form in the formset.


Returns the number of errors across all forms in the formset.


Returns true if every form in the formset is valid.


Cleans all of and populates formset error objects.


Hook for doing any extra formset-wide cleaning after BaseForm.clean() has been called on every form.

Any ValidationError() raised by this method will not be associated with a particular form; it will be accesible via :js:func:BaseFormSet#nonFormErrors


Returns true if any form differs from initial.

A number of default rendering functions are provided to generate ReactElement representations of a FormSet’s fields.

These are general-purpose in that they attempt to handle all form rendering scenarios and edge cases, ensuring that valid markup is always produced.

For flexibility, the output does not include a <form> or a submit button, just field labels and inputs.

Deprecated since version 0.10: Default rendering methods are deprecated in favour of providing React Components for default rendering.


Default rendering method, which calls BaseFormSet#asTable()

New in version 0.5.

Deprecated since version 0.10.


Renders the formset’s forms as a series of <tr> tags, with <th> and <td> tags containing field labels and inputs, respectively.

Deprecated since version 0.10.


Renders the formset’s forms as a series of <div> tags, with each <div> containing one field.

New in version 0.5.

Deprecated since version 0.10.

Prototype functions for use in rendering forms.


Returns the default base prefix for each form: 'form'.

BaseFormSet#addFields(form, index)

A hook for adding extra fields on to a form instance.

  • form (Form) – the form fields will be added to.
  • index (Number) – the index of the given form in the formset.

Returns a formset prefix with the given form index appended.

  • index (Number) – the index of a form in the formset.

Returns true if the formset needs to be multipart-encoded, i.e. it has a FileInput(). Otherwise, false.


formsetFactory(form[, kwargs])

Returns a FormSet constructor for the given Form constructor.

  • form (Function) – the constructor for the Form to be managed.
  • kwargs (Object) – arguments defining options for the created FormSet constructor - all arguments other than those defined below will be added to the new formset constructor’s prototype, so this object can also be used to define new methods on the resulting formset, such as a custom clean method.
  • kwargs.formset (Function) – the constructuer which will provide the prototype for the created FormSet constructor – defaults to BaseFormSet().
  • kwargs.extra (Number) – the number of extra forms to be displayed – defaults to 1.
  • kwargs.canOrder (Boolean) – if true, forms can be ordered – defaults to false.
  • kwargs.canDelete (Boolean) – if true, forms can be deleted – defaults to false.
  • kwargs.maxNum (Number) – the maximum number of forms to be displayed – defaults to DEFAULT_MAX_NUM.
  • kwargs.validateMax (Boolean) – if true, validation will also check that the number of forms in the data set, minus those marked for deletion, is less than or equal to maxNum.
  • kwargs.minNum (Number) – the minimum number of forms to be displayed – defaults to 0.
  • kwargs.validateMin (Boolean) – if true, validation will also check that the number of forms in the data set, minus those marked for deletion, is greater than or equal to minNum.

The default maximum number of forms in a formet is 1000, to protect against memory exhaustion.