Version 2 (modified by anonymous, 12 years ago) (diff)



Since newforms is mostly undocumented at the moment this page summarizes some useful information. This documentation should be considered complementary to the documentation on It's mostly information extracted from the unit tests for newforms at the moment.

Widgets Unit tests

Each Widget class corresponds to an HTML form widget. A Widget knows how to render itself, given a field name and some data. Widgets don't perform validation.

Widget types

List of widget types with their associated unit test for easy lookup.

TextInput Unit test
PasswordInput Unit test
HiddenInput Unit test
FileInput Unit test
TextArea Unit test
CheckBoxInput Unit test
Select Unit test
SelectMultiple Unit test
RadioSelect Unit test
CheckBoxSelectMultiple Unit test


Each Field class does some sort of validation. Each Field has a clean() method, which either raises django.newforms.ValidationError or returns the "clean" data -- usually a Unicode object, but, in some rare cases, a list.

Each Field's init() takes at least these parameters:

  • required -- Boolean that specifies whether the field is required. True by default.
  • widget -- A Widget class, or instance of a Widget class, that should be used for this Field when displaying it. Each Field has a
  • default -- Widget that it'll use if you don't specify this. In most cases, the default widget is TextInput.
  • label -- A verbose name for this field, for use in displaying this field in a form. By default, Django will use a "pretty" version of the form field name, if the Field is part of a Form.
  • initial -- A value to use in this Field's initial display. This value is *not* used as a fallback if data isn't given.

Other than that, the Field subclasses have class-specific options for init(). For example, CharField has a max_length option.

Field types Unit tests

List of field types with their associated unit test for easy lookup.

CharField Unit test


  • max_length -- (optional) Maximum number of characters
  • min_length -- (optional) Minimum number of characters
IntegerField Unit test


  • max_value -- (optional) Maximum value
  • min_value -- (optional) Minimum value
DateField Unit test


  • input_formats -- (optional) A list of strftime() input formats. These will override all other input formats
TimeField Unit test
DateTimeField Unit test
RegexField Unit test


  • regex -- The regular expression in compiled or string form that the input should match
EmailField Unit test


  • min_length -- Minimum length
  • max_length -- Maximum length
URLField Unit test
BooleanField Unit test

Since html forms either return something like 'fieldname=on' in request.POST or request.GET, this value may not be set in form.clean_data.


  • None
ChoiceField Unit test


  • choices -- A list of (key, value) pairs
MultipleChoiceField Unit test


  • choices -- A list of (key, value) pairs
ComboField Unit test

ComboField takes a list of fields that should be used to validate a value, in that order.


  • choices -- A list of fields used to validate the input value

Forms Unit test

A Form is a collection of Fields. It knows how to validate a set of data and it knows how to render itself in a couple of default ways (e.g., an HTML table). You can pass it data in init(), as a dictionary.

Back to Top