Form Fields - Django

Base Field Class

All form fields inherit from the base Field class.

Field(
    required=True,
    widget=None,
    label=None,
    initial=None,
    help_text="",
    error_messages=None,
    show_hidden_initial=False,
    validators=(),
    localize=False,
    disabled=False,
    label_suffix=None,
    template_name=None,
    bound_field_class=None
)

required

bool

default:"True"

Whether the field is required. If True, validation fails if field is empty.

Widget instance to use for rendering. Each field has a default widget.

label

str

Human-readable label for the field. Auto-generated from field name if not provided.

initial

any

Initial value for the field in unbound forms.

help_text

str

default:"''"

Help text to display with the field.

error_messages

dict

Dictionary of error codes to custom error messages.

show_hidden_initial

bool

default:"False"

Whether to render a hidden widget with the initial value.

validators

list

List of additional validator functions to apply.

localize

bool

default:"False"

Whether to localize field input and output.

disabled

bool

default:"False"

Whether the field is disabled (shown but not editable).

label_suffix

str

Suffix to append to the label. Overrides form-level setting.

Text Fields

CharField

Accepts text input.

CharField(
    max_length=None,
    min_length=None,
    strip=True,
    empty_value="",
    **kwargs
)

max_length

int

Maximum number of characters allowed.

min_length

int

Minimum number of characters required.

strip

bool

default:"True"

Whether to strip leading and trailing whitespace.

empty_value

str

default:"''"

Value to return for empty input.

name = forms.CharField(
    max_length=100,
    min_length=2,
    label="Your Name",
    help_text="Enter your full name"
)

EmailField

Validates that input is a valid email address.

EmailField(**kwargs)

Default widget: EmailInput
Default max_length: 320 (per RFC 3696)

email = forms.EmailField(
    required=True,
    error_messages={'invalid': 'Please enter a valid email address'}
)

URLField

Validates that input is a valid URL.

URLField(
    assume_scheme="https",
    **kwargs
)

assume_scheme

str

default:"https"

Scheme to prepend if none provided (e.g., “https”, “http”).

Default widget: URLInput

website = forms.URLField(
    required=False,
    assume_scheme="https"
)

SlugField

Validates input contains only letters, numbers, underscores, or hyphens.

SlugField(
    allow_unicode=False,
    **kwargs
)

allow_unicode

bool

default:"False"

Whether to allow Unicode letters in addition to ASCII.

slug = forms.SlugField(max_length=50)

RegexField

Validates input against a regular expression.

RegexField(
    regex,
    **kwargs
)

regex

str | Pattern

required

Regular expression string or compiled pattern object.

phone = forms.RegexField(
    regex=r'^\d{3}-\d{3}-\d{4}$',
    error_messages={'invalid': 'Enter format: XXX-XXX-XXXX'}
)

Numeric Fields

IntegerField

Validates that input is a valid integer.

IntegerField(
    max_value=None,
    min_value=None,
    step_size=None,
    **kwargs
)

max_value

int

Maximum allowed value.

min_value

int

Minimum allowed value.

step_size

int

Value must be a multiple of this number.

Default widget: NumberInput

age = forms.IntegerField(
    min_value=0,
    max_value=120,
    error_messages={'invalid': 'Enter a valid age'}
)

FloatField

Validates that input is a valid floating-point number.

FloatField(
    max_value=None,
    min_value=None,
    step_size=None,
    **kwargs
)

Default widget: NumberInput

price = forms.FloatField(
    min_value=0.0,
    max_value=9999.99
)

DecimalField

Validates that input is a valid decimal number.

DecimalField(
    max_value=None,
    min_value=None,
    max_digits=None,
    decimal_places=None,
    **kwargs
)

max_digits

int

Maximum number of total digits allowed.

decimal_places

int

Maximum number of decimal places allowed.

Default widget: NumberInput

amount = forms.DecimalField(
    max_digits=10,
    decimal_places=2,
    min_value=0
)

Date and Time Fields

DateField

Validates that input is a valid date.

DateField(
    input_formats=None,
    **kwargs
)

input_formats

list

List of date format strings to accept (e.g., ['%Y-%m-%d', '%m/%d/%Y']).

Default widget: DateInput
Returns: datetime.date object

birthdate = forms.DateField(
    widget=forms.DateInput(attrs={'type': 'date'})
)

TimeField

Validates that input is a valid time.

TimeField(
    input_formats=None,
    **kwargs
)

Default widget: TimeInput
Returns: datetime.time object

appointment_time = forms.TimeField(
    widget=forms.TimeInput(attrs={'type': 'time'})
)

DateTimeField

Validates that input is a valid date and time.

DateTimeField(
    input_formats=None,
    **kwargs
)

Default widget: DateTimeInput
Returns: datetime.datetime object

published_at = forms.DateTimeField()

DurationField

Validates that input is a valid duration.

DurationField(**kwargs)

Accepts formats like: "2 days", "1:30:00", "P3DT4H5M6S" (ISO 8601)
Returns: datetime.timedelta object

video_length = forms.DurationField()

Choice Fields

ChoiceField

Validates that input is one of a set of valid choices.

ChoiceField(
    choices=(),
    **kwargs
)

choices

list

required

List of 2-tuples (value, label) or nested groups.

Default widget: Select

STATUS_CHOICES = [
    ('draft', 'Draft'),
    ('published', 'Published'),
    ('archived', 'Archived'),
]

status = forms.ChoiceField(
    choices=STATUS_CHOICES,
    initial='draft'
)

TypedChoiceField

Like ChoiceField but coerces the value to a specific type.

TypedChoiceField(
    choices=(),
    coerce=lambda val: val,
    empty_value="",
    **kwargs
)

coerce

callable

default:"lambda val: val"

Function to coerce the value to the desired type.

empty_value

any

default:"''"

Value to return for empty input.

rating = forms.TypedChoiceField(
    choices=[(1, 'One'), (2, 'Two'), (3, 'Three')],
    coerce=int
)

MultipleChoiceField

Validates that input is one or more of valid choices.

MultipleChoiceField(
    choices=(),
    **kwargs
)

Default widget: SelectMultiple
Returns: List of strings

TAG_CHOICES = [
    ('python', 'Python'),
    ('django', 'Django'),
    ('javascript', 'JavaScript'),
]

tags = forms.MultipleChoiceField(
    choices=TAG_CHOICES,
    required=False
)

TypedMultipleChoiceField

Like MultipleChoiceField but coerces values to a specific type.

TypedMultipleChoiceField(
    choices=(),
    coerce=lambda val: val,
    empty_value=[],
    **kwargs
)

years = forms.TypedMultipleChoiceField(
    choices=[(2021, '2021'), (2022, '2022'), (2023, '2023')],
    coerce=int
)

Boolean Fields

BooleanField

Validates that input is boolean (checkbox).

BooleanField(**kwargs)

Default widget: CheckboxInput
Returns: True or False

agree_to_terms = forms.BooleanField(
    required=True,
    error_messages={'required': 'You must agree to the terms'}
)

NullBooleanField

A boolean field that accepts None as a value.

NullBooleanField(**kwargs)

Default widget: NullBooleanSelect
Returns: True, False, or None

is_active = forms.NullBooleanField(required=False)

File Fields

FileField

Validates file upload.

FileField(
    max_length=None,
    allow_empty_file=False,
    **kwargs
)

max_length

int

Maximum length of the filename.

allow_empty_file

bool

default:"False"

Whether to allow empty files (0 bytes).

Default widget: ClearableFileInput
Returns: UploadedFile object

attachment = forms.FileField(
    required=False,
    help_text="Max file size: 5MB"
)

ImageField

Validates that uploaded file is a valid image.

ImageField(**kwargs)

Requires: Pillow library
Default widget: ClearableFileInput
Returns: UploadedFile object with image validation

avatar = forms.ImageField(
    required=False,
    help_text="Upload a profile picture"
)

FilePathField

Allows selection of files from server filesystem.

FilePathField(
    path,
    match=None,
    recursive=False,
    allow_files=True,
    allow_folders=False,
    **kwargs
)

path

str

required

Absolute filesystem path to directory.

match

str

Regular expression pattern to filter filenames.

recursive

bool

default:"False"

Whether to include subdirectories.

allow_files

bool

default:"True"

Whether to include files.

allow_folders

bool

default:"False"

Whether to include folders.

template = forms.FilePathField(
    path="/path/to/templates/",
    match=r'\.html$',
    recursive=True
)

Network Fields

GenericIPAddressField

Validates that input is a valid IP address.

GenericIPAddressField(
    protocol="both",
    unpack_ipv4=False,
    **kwargs
)

protocol

str

default:"both"

Protocol to validate: "both", "ipv4", or "ipv6".

unpack_ipv4

bool

default:"False"

Whether to unpack IPv4-mapped IPv6 addresses.

ip_address = forms.GenericIPAddressField(
    protocol="ipv4"
)

Special Fields

JSONField

Validates that input is valid JSON.

JSONField(
    encoder=None,
    decoder=None,
    **kwargs
)

encoder

JSONEncoder

Custom JSON encoder class.

decoder

JSONDecoder

Custom JSON decoder class.

Default widget: Textarea
Returns: Parsed JSON data (dict, list, etc.)

metadata = forms.JSONField(
    required=False,
    help_text="Enter valid JSON"
)

UUIDField

Validates that input is a valid UUID.

UUIDField(**kwargs)

Returns: uuid.UUID object

identifier = forms.UUIDField()

Composite Fields

ComboField

Validates input against multiple fields sequentially.

ComboField(
    fields,
    **kwargs
)

fields

list

required

List of Field instances to validate against.

secure_password = forms.ComboField(
    fields=[
        forms.CharField(min_length=8),
        forms.RegexField(regex=r'[A-Z]', error_messages={'invalid': 'Need uppercase'}),
        forms.RegexField(regex=r'[0-9]', error_messages={'invalid': 'Need number'}),
    ]
)

MultiValueField

Aggregates multiple fields into a single field.

MultiValueField(
    fields,
    require_all_fields=True,
    **kwargs
)

fields

list

required

List of Field instances.

require_all_fields

bool

default:"True"

Whether all sub-fields are required.

Must implement compress() method to combine field values.

SplitDateTimeField

Splits datetime input into separate date and time fields.

SplitDateTimeField(
    input_date_formats=None,
    input_time_formats=None,
    **kwargs
)

Default widget: SplitDateTimeWidget
Returns: datetime.datetime object

event_datetime = forms.SplitDateTimeField()

Field Methods

All fields inherit these methods:

clean()

field.clean(value) -> any

Validates and returns cleaned data. Raises ValidationError if invalid.

to_python()

field.to_python(value) -> any

Converts input value to appropriate Python type.

validate()

field.validate(value) -> None

Performs field-specific validation.

run_validators()

field.run_validators(value) -> None

Runs all validators attached to the field.

has_changed()

field.has_changed(initial, data) -> bool

Returns True if data differs from initial value.

Core APIs

Models

Views & URLs

Templates

Forms

Utilities

​Base Field Class

​Text Fields

​CharField

​EmailField

​URLField

​SlugField

​RegexField

​Numeric Fields

​IntegerField

​FloatField

​DecimalField

​Date and Time Fields

​DateField

​TimeField

​DateTimeField

​DurationField

​Choice Fields

​ChoiceField

​TypedChoiceField

​MultipleChoiceField

​TypedMultipleChoiceField

​Boolean Fields

​BooleanField

​NullBooleanField

​File Fields

​FileField

​ImageField

​FilePathField

​Network Fields

​GenericIPAddressField

​Special Fields

​JSONField

​UUIDField

​Composite Fields

​ComboField

​MultiValueField

​SplitDateTimeField

​Field Methods

​clean()

​to_python()

​validate()

​run_validators()

​has_changed()

Build docs developers (and LLMs) love

Base Field Class

Text Fields

CharField

EmailField

URLField

SlugField

RegexField

Numeric Fields

IntegerField

FloatField

DecimalField

Date and Time Fields

DateField

TimeField

DateTimeField

DurationField

Choice Fields

ChoiceField

TypedChoiceField

MultipleChoiceField

TypedMultipleChoiceField

Boolean Fields

BooleanField

NullBooleanField

File Fields

FileField

ImageField

FilePathField

Network Fields

GenericIPAddressField

Special Fields

JSONField

UUIDField

Composite Fields

ComboField

MultiValueField

SplitDateTimeField

Field Methods

clean()

to_python()

validate()

run_validators()

has_changed()