Built-in widgets¶

https://docs.djangoproject.com/en/1.8/ref/forms/widgets/

Built-in widgets¶

Django provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets in thedjango.forms.widgets module, including the input of text, various checkboxes and selectors, uploading files, andhandling of multi-valued input.

Widgets handling input of text¶

These widgets make use of the HTML elements input and textarea.

TextInput¶

class TextInput¶

Text input: <input type="text" ...>

NumberInput¶

class NumberInput¶

Text input: <input type="number" ...>

Beware that not all browsers support entering localized numbers in number input types. Django itself avoids using them for fields having their localize property set to True.

EmailInput¶

class EmailInput¶

Text input: <input type="email" ...>

URLInput¶

class URLInput¶

Text input: <input type="url" ...>

PasswordInput¶

class PasswordInput¶

Password input: <input type='password' ...>

Takes one optional argument:

render_value¶

Determines whether the widget will have a value filled in when the form is re-displayed after a validation error (default is False).

HiddenInput¶

class HiddenInput¶

Hidden input: <input type='hidden' ...>

Note that there also is a MultipleHiddenInput widget that encapsulates a set of hidden input elements.

DateInput¶

class DateInput¶

Date input as a simple text box: <input type='text' ...>

Takes same arguments as TextInput, with one more optional argument:

format¶

The format in which this field’s initial value will be displayed.

If no format argument is provided, the default format is the first format found in DATE_INPUT_FORMATS and respectsFormat localization.

DateTimeInput¶

class DateTimeInput¶

Date/time input as a simple text box: <input type='text' ...>

Takes same arguments as TextInput, with one more optional argument:

format¶

The format in which this field’s initial value will be displayed.

If no format argument is provided, the default format is the first format found in DATETIME_INPUT_FORMATS and respects Format localization.

TimeInput¶

class TimeInput¶

Time input as a simple text box: <input type='text' ...>

Takes same arguments as TextInput, with one more optional argument:

format¶

The format in which this field’s initial value will be displayed.

If no format argument is provided, the default format is the first format found in TIME_INPUT_FORMATS and respectsFormat localization.

Textarea¶

class Textarea¶

Text area: <textarea>...</textarea>

Selector and checkbox widgets¶

CheckboxInput¶

class CheckboxInput¶

Checkbox: <input type='checkbox' ...>

Takes one optional argument:

check_test¶

A callable that takes the value of the CheckboxInput and returns True if the checkbox should be checked for that value.

Select¶

class Select¶

Select widget: <select><option ...>...</select>

choices¶

This attribute is optional when the form field does not have a choices attribute. If it does, it will override anything you set here when the attribute is updated on the Field.

NullBooleanSelect¶

class NullBooleanSelect¶

Select widget with options ‘Unknown’, ‘Yes’ and ‘No’

SelectMultiple¶

class SelectMultiple¶

Similar to Select, but allows multiple selection: <select multiple='multiple'>...</select>

RadioSelect¶

class RadioSelect¶

Similar to Select, but rendered as a list of radio buttons within <li> tags:

<ul>
  <li><input type='radio' name='...'></li>
  ...
</ul>

For more granular control over the generated markup, you can loop over the radio buttons in the template. Assuming a form myform with a field beatles that uses a RadioSelect as its widget:

{% for radio in myform.beatles %}
<div class="myradio">
    {{ radio }}
</div>
{% endfor %}

This would generate the following HTML:

<div class="myradio">
    <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" /> John</label>
</div>
<div class="myradio">
    <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" /> Paul</label>
</div>
<div class="myradio">
    <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" /> George</label>
</div>
<div class="myradio">
    <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" /> Ringo</label>
</div>

That included the <label> tags. To get more granular, you can use each radio button’s tag, choice_label andid_for_label attributes. For example, this template...

{% for radio in myform.beatles %}
    <label for="{{ radio.id_for_label }}">
        {{ radio.choice_label }}
        <span class="radio">{{ radio.tag }}</span>
    </label>
{% endfor %}

...will result in the following HTML:

<label for="id_beatles_0">
    John
    <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" /></span>
</label>

<label for="id_beatles_1">
    Paul
    <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" /></span>
</label>

<label for="id_beatles_2">
    George
    <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" /></span>
</label>

<label for="id_beatles_3">
    Ringo
    <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" /></span>
</label>

If you decide not to loop over the radio buttons – e.g., if your template simply includes {{ myform.beatles }} – they’ll be output in a <ul> with <li> tags, as above.

The outer <ul> container will receive the id attribute defined on the widget.

Changed in Django 1.7:

When looping over the radio buttons, the label and input tags include for and id attributes, respectively. Each radio button has an id_for_label attribute to output the element’s ID.

CheckboxSelectMultiple¶

class CheckboxSelectMultiple¶

Similar to SelectMultiple, but rendered as a list of check buttons:

<ul>
  <li><input type='checkbox' name='...' ></li>
  ...
</ul>

The outer <ul> container will receive the id attribute defined on the widget.

Like RadioSelect, you can now loop over the individual checkboxes making up the lists. See the documentation ofRadioSelect for more details.

Changed in Django 1.7:

When looping over the checkboxes, the label and input tags include for and id attributes, respectively. Each checkbox has an id_for_label attribute to output the element’s ID.

File upload widgets¶

FileInput¶

class FileInput¶

File upload input: <input type='file' ...>

ClearableFileInput¶

class ClearableFileInput¶

File upload input: <input type='file' ...>, with an additional checkbox input to clear the field’s value, if the field is not required and has initial data.

Composite widgets¶

MultipleHiddenInput¶

class MultipleHiddenInput¶

Multiple <input type='hidden' ...> widgets.

A widget that handles multiple hidden widgets for fields that have a list of values.

choices¶

This attribute is optional when the form field does not have a choices attribute. If it does, it will override anything you set here when the attribute is updated on the Field.

SplitDateTimeWidget¶

class SplitDateTimeWidget¶

Wrapper (using MultiWidget) around two widgets: DateInput for the date, and TimeInput for the time.

SplitDateTimeWidget has two optional attributes:

date_format¶

Similar to DateInput.format

time_format¶

Similar to TimeInput.format

SplitHiddenDateTimeWidget¶

class SplitHiddenDateTimeWidget¶

Similar to SplitDateTimeWidget, but uses HiddenInput for both date and time.

SelectDateWidget¶

class SelectDateWidget[source]¶

Wrapper around three Select widgets: one each for month, day, and year. Note that this widget lives in a separate file from the standard widgets.

Takes several optional arguments:

years¶

An optional list/tuple of years to use in the “year” select box. The default is a list containing the current year and the next 9 years.

months¶

New in Django 1.7.

An optional dict of months to use in the “months” select box.

The keys of the dict correspond to the month number (1-indexed) and the values are the displayed months:

MONTHS = {
    1:_('jan'), 2:_('feb'), 3:_('mar'), 4:_('apr'),
    5:_('may'), 6:_('jun'), 7:_('jul'), 8:_('aug'),
    9:_('sep'), 10:_('oct'), 11:_('nov'), 12:_('dec')
}

empty_label¶

New in Django 1.8.

If the DateField is not required, SelectDateWidget will have an empty choice at the top of the list (which is ---by default). You can change the text of this label with the empty_label attribute. empty_label can be a string,list, or tuple. When a string is used, all select boxes will each have an empty choice with this label. Ifempty_label is a list or tuple of 3 string elements, the select boxes will have their own custom label. The labels should be in this order ('year_label', 'month_label', 'day_label').

# A custom empty label with string
field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing"))

# A custom empty label with tuple
field1 = forms.DateField(
    widget=SelectDateWidget(
        empty_label=("Choose Year", "Choose Month", "Choose Day"),
    ),
)