material_widgets.widgets¶

Customized form field widgets with templates styled with Material Components for the Web.

References

class material_widgets.widgets.MaterialCheckboxInput(label=None, help_text=None, *args, **kwargs)[source]¶

Material CheckboxInput

Default widget for BooleanField under MaterialForm.

Parameters:	label (str, optional) – Displayed to the right of the checkbox. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed as a tool tip on the label.

Examples

Explicit widget declaration is unnecessary in a BooleanField under a MaterialForm.

>>> checkbox = forms.BooleanField(
>>>     label='Checkbox',
>>>     help_text='This is a checkbox',
>>>     #widget=MaterialCheckboxInput(),
>>>     )

class material_widgets.widgets.MaterialCheckboxSelectMultiple(is_vertical=True, *args, **kwargs)[source]¶

Material CheckboxSelectMultiple

Other Parameters:
Parameters:	label (str, optional) – Displayed above the checkbox group. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (list or tuple of str, optional) – Displayed as tool tips on the respective checkbox labels. choices (list or tuple of (value, label) pairs) – Each pair will be displayed as a checkbox.
	is_vertical (bool, optional) – Layout of checkboxes will be vertical if True, or horizontal otherwise. Defaults to True.

Examples

Declare widget explicity to use custom widget parameters.

>>> checkbox_select_multiple = forms.MultipleChoiceField(
>>>     label='Multiple Checkboxes',
>>>     help_text=(
>>>         'This is checkbox 1',
>>>         'This is checkbox 2',
>>>         'This is checkbox 3',
>>>         ),
>>>     widget=MaterialCheckboxSelectMultiple(
>>>         is_vertical=False,
>>>         ),
>>>     choices=(
>>>         ('checkbox_1', 'Checkbox 1'),
>>>         ('checkbox_2', 'Checkbox 2'),
>>>         ('checkbox_3', 'Checkbox 3'),
>>>         ),
>>>     )

class material_widgets.widgets.MaterialClearableFileInput(button=None, icon=None, *args, **kwargs)[source]¶

Material ClearableFileInput

Default widget for FileField and ImageField under MaterialForm.

Other Parameters:
Parameters:	label (str, optional) – Displayed on the button. Defaults to widget’s capitalized field name with underscores converted to spaces. Label dynamically changes to selected file name, or file count if the ‘multiple’ attrs is True. help_text (str, optional) – Displayed as a tool tip on the button.
	button (list or tuple of str, optional) – Button style modifiers include ‘compact’, ‘dense’, ‘raised’, ‘stroked’, and ‘unelevated’. See mdc-button CSS Classes for details. icon (str, optional) – Icon to be displayed on the file button. See Material Icons for choices.

Examples

Declare widget explicity to use custom widget parameters.

>>> clearable_file_input = forms.FileField(
>>>     ### Blank the label to only display the icon
>>>     label='',
>>>     help_text='Choose 1 or more files',
>>>     widget=MaterialClearableFileInput(
>>>         ### compact, dense, raised, stroked, unelevated
>>>         button=('compact', 'dense', 'raised'),
>>>         ### From material-icons; https://material.io/icons/
>>>         icon='file_upload',
>>>         attrs={
>>>             'multiple': True,
>>>             },
>>>         ),
>>>     )

class material_widgets.widgets.MaterialDateInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material DateInput

Default widget for DateField under MaterialForm.

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> date_field = forms.DateField(
>>>     label='Date',
>>>     help_text='YYYY-MM-DD',
>>>     widget=MaterialDateInput(
>>>         persistent_help_text=True,
>>>         ),
>>>     )

class material_widgets.widgets.MaterialDateTimeInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material DateTimeInput

Default widget for DateTimeField under MaterialForm.

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> datetime_field = forms.DateTimeField(
>>>     label='Date and Time',
>>>     help_text='YYYY-MM-DD HH:MM:SS',
>>>     widget=MaterialDateTimeInput(
>>>         persistent_help_text=True,
>>>         ),
>>>     )

class material_widgets.widgets.MaterialEmailInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material EmailInput

Default widget for EmailField under MaterialForm.

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> email = forms.EmailField(
>>>     label='Email Address',
>>>     help_text='your_email@example.com',
>>>     widget=MaterialEmailInput(
>>>         persistent_help_text=True,
>>>         ),
>>>     )

class material_widgets.widgets.MaterialFileInput(button=None, icon=None, *args, **kwargs)[source]¶

Material FileInput

Other Parameters:
Parameters:	label (str, optional) – Displayed on the button. Defaults to widget’s capitalized field name with underscores converted to spaces. Label dynamically changes to selected file name, or file count if the ‘multiple’ attrs is True. help_text (str, optional) – Displayed as a tool tip on the button.
	button (list or tuple of str, optional) – Button style modifiers include ‘compact’, ‘dense’, ‘raised’, ‘stroked’, and ‘unelevated’. See mdc-button CSS Classes for details. icon (str, optional) – Icon to be displayed on the file button. See Material Icons for choices.

Examples

Declare widget explicity to use custom widget parameters.

>>> file_input = forms.FileField(
>>>     ### Blank the label to only display the icon
>>>     label='',
>>>     help_text='Choose 1 or more files',
>>>     widget=MaterialFileInput(
>>>         ### compact, dense, raised, stroked, unelevated
>>>         button=('compact', 'dense', 'raised'),
>>>         ### From material-icons; https://material.io/icons/
>>>         icon='attachment',
>>>         attrs={
>>>             'multiple': True,
>>>             },
>>>         ),
>>>     )

class material_widgets.widgets.MaterialHiddenInput(label=None, help_text=None, *args, **kwargs)[source]¶

Material HiddenInput

Parameters:	initial (varies depending on field, optional) – Initial value to populate the hidden input in the form.

Examples

>>> hidden_input = forms.CharField(
>>>     initial='hidden_value',
>>>     widget=widgets.HiddenInput(),
>>>     )

class material_widgets.widgets.MaterialMultipleHiddenInput(label=None, help_text=None, *args, **kwargs)[source]¶

Material MultipleHiddenInput

Parameters:	initial (varies depending on field, optional) – Initial Value to populate the multiple hidden input in the form.

Examples

>>> multiple_hidden_input = forms.MultipleChoiceField(
>>>     initial=['hidden_1', 'hidden_2', 'hidden_3',],
>>>     widget=widgets.MultipleHiddenInput(),
>>>     choices=(
>>>         ('hidden_1', 'Hidden 1'),
>>>         ('hidden_2', 'Hidden 2'),
>>>         ('hidden_3', 'Hidden 3'),
>>>         ),
>>>     )

class material_widgets.widgets.MaterialNullBooleanSelect(label=None, help_text=None, *args, **kwargs)[source]¶

Material NullBooleanSelect

Default widget for NullBooleanField under MaterialForm.

Parameters:	label (str, optional) – Displayed to the left of the select menu. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed as a tool tip on the label.

Examples

Explicit widget declaration is unnecessary in a NullBooleanField under a MaterialForm.

>>> null_boolean_select = forms.NullBooleanField(
>>>     label='Is this a null boolean select?',
>>>     help_text='This is a null boolean select',
>>>     #widget=MaterialNullBooleanSelect(),
>>>     )

class material_widgets.widgets.MaterialNumberInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material NumberInput

Default widget for DecimalField, FloatField, and IntegerField under MaterialForm when Field.localize is False.

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Explicit widget declaration is unnecessary in a DecimalField, FloatField, or IntegerField under MaterialForm.

>>> decimal = forms.DecimalField(
>>>     label='Decimal Number',
>>>     help_text='To 2 d.p.',
>>>     min_value=0.0,
>>>     max_value=10.0,
>>>     decimal_places=2,
>>>     )

Declare widget explicity to use custom widget parameters.

>>> integer = forms.IntegerField(
>>>     label='Odd Number',
>>>     help_text='No even numbers!',
>>>     min_value=1,
>>>     max_value=9,
>>>     widget=widgets.NumberInput(
>>>         persistent_help_text=True,
>>>         attrs={
>>>             'step': '2',
>>>             },
>>>         ),
>>>     )

class material_widgets.widgets.MaterialPasswordInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material PasswordInput

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> password = forms.CharField(
>>>     label="Secret Password",
>>>     help_text='Please enter at least 8 characters',
>>>     min_length=8,
>>>     widget=MaterialPasswordInput(
>>>         persistent_help_text=True,
>>>         ),
>>>     )

class material_widgets.widgets.MaterialRadioSelect(is_vertical=False, *args, **kwargs)[source]¶

Material RadioSelect

Other Parameters:
Parameters:	label (str, optional) – Displayed above the radio group. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (list or tuple of str, optional) – Displayed as tool tips on the respective radio option labels. choices (list or tuple of (value, label) pairs) – Each pair will be displayed as a radio option.
	is_vertical (bool, optional) – Layout of checkboxes will be vertical if True, or horizontal otherwise. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> radio_select = forms.ChoiceField(
>>>     label='Radio Select',
>>>     help_text=(
>>>         'This is radio 1',
>>>         'This is radio 2',
>>>         'This is radio 3',
>>>         ),
>>>     widget=widgets.RadioSelect(
>>>         is_vertical=True,
>>>         ),
>>>     choices=(
>>>         ('radio_select_1', 'Radio 1'),
>>>         ('radio_select_2', 'Radio 2'),
>>>         ('radio_select_3', 'Radio 3'),
>>>         ),
>>>     )

class Media[source]¶: Material radio JS component.

class material_widgets.widgets.MaterialSelect(label=None, help_text=None, *args, **kwargs)[source]¶

Material Select

Default widget for ChoiceField, FilePathField, ModelChoiceField, and TypedChoiceField under MaterialForm.

Parameters:	label (str, optional) – Displayed to the left of the select menu. If explicitly declared blank, the first item in the select menu will act as an unselectable choice label. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed as a tool tip on the label.

Examples

Explicit widget declaration is unnecessary in ChoiceField, FilePathField, ModelChoiceField, and TypedChoiceField under MaterialForm.

>>> select = forms.ChoiceField(
>>>     label='',
>>>     #widget=MaterialSelect(),
>>>     choices=(
>>>         ('', 'Select'),
>>>         ('choice_1', 'Choice 1'),
>>>         ('choice_2', 'Choice 2'),
>>>         ('choice_3', 'Choice 3'),
>>>         ),
>>>     )

Choices can be grouped.

>>> select_with_groups = forms.ChoiceField(
>>>     label='',
>>>     required=False,
>>>     choices=(
>>>         ('', 'Select with Groups'),
>>>         ('Group 1', (
>>>             ('group_1_choice_1', 'Group 1 Choice 1 '),
>>>             ('group_1_choice_2', 'Group 1 Choice 2'),
>>>             ('group_1_choice_3', 'Group 1 Choice 3'),
>>>             )
>>>         ),
>>>         ('Group 2', (
>>>             ('group_2_choice_4', 'Group 2 Choice 4'),
>>>             ('group_2_choice_5', 'Group 2 Choice 5'),
>>>             ('group_2_choice_6', 'Group 2 Choice 6'),
>>>             )
>>>         ),
>>>         ),
>>>     )

class material_widgets.widgets.MaterialSelectDateWidget(label=None, help_text=None, *args, **kwargs)[source]¶

Material SelectDateWidget

Other Parameters:
Parameters:	label (str, optional) – Displayed to the left of the select menu. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed as a tool tip on the label.
	various (various, optional) – See django.forms.widgets.SelectDateWidget for optional parameters.

Examples

Widget can be declared as Django’s SelectDateWidget or as MaterialSelectDateWidget.

>>> date_select = forms.DateField(
>>>     label="Date",
>>>     help_text='This is a select date',
>>>     widget=widgets.SelectDateWidget(
>>>         years=[year for year in range(
>>>             datetime.now().year, datetime.now().year-100, -1)
>>>               ],
>>>         empty_label=("Year", "Month", "Day"),
>>>         )
>>>     )

class Media[source]¶: Material multiwidget CSS component.

select_widget¶: alias of MaterialSelect

class material_widgets.widgets.MaterialSelectMultiple(label=None, help_text=None, *args, **kwargs)[source]¶

Material SelectMultiple

Default widget for MultipleChoiceField, ModelMultipleChoiceField, and TypedMultipleChoiceField under MaterialForm.

Parameters:	label (str, optional) – Displayed to the left of the select menu. If explicitly declared blank, the first item in the select menu will act as an unselectable choice label. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed as a tool tip on the label.

Examples

Explicit widget declaration is unnecessary in MultipleChoiceField, ModelMultipleChoiceField, and TypedMultipleChoiceField under MaterialForm.

>>> select_multiple = forms.MultipleChoiceField(
>>>     label='Choose 1 or more',
>>>     help_text='Ctrl + Click to unselect',
>>>     #widget=MaterialSelect(),
>>>     choices=(
>>>         ('', 'Select'),
>>>             ('multiple_choice_1', 'Multiple Choice 1'),
>>>             ('multiple_choice_2', 'Multiple Choice 2'),
>>>             ('multiple_choice_3', 'Multiple Choice 3'),
>>>         ),
>>>     )

Choices can be grouped.

>>> select_multiple_with_groups = forms.MultipleChoiceField(
>>>     label='',
>>>     #help_text='A label is needed to show the help text tooltip',
>>>     choices=(
>>>         ('Select Multiple 1', (
>>>             ('multiple_choice_1', 'Multiple Choice 1'),
>>>             ('multiple_choice_2', 'Multiple Choice 2'),
>>>             ('multiple_choice_3', 'Multiple Choice 3'),
>>>             )
>>>         ),
>>>         ('Select Multiple 2', (
>>>             ('multiple_choice_4', 'Multiple Choice 4'),
>>>             ('multiple_choice_5', 'Multiple Choice 5'),
>>>             ('multiple_choice_6', 'Multiple Choice 6'),
>>>             )
>>>         ),
>>>         ),
>>>     )

class material_widgets.widgets.MaterialSliderInput(display_markers=False, is_discrete=False, persistent_help_text=True, *args, **kwargs)[source]¶

Material SliderInput

Parameters:

label (str, optional) – Displayed above the widget in the template. Defaults to widget’s capitalized field name with underscores converted to spaces.
help_text (str, optional) – Displayed to the right of the label.

Other Parameters:

persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to True.
is_discrete (bool, optional) – Slider will have discrete steps in its interface if True, else its interface will be continuous. Defaults to False.
display_markers (bool, optional) – Value markers appear on slider interaction if True. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> slider = forms.IntegerField(
>>>     label='Slider',
>>>     ### help_text in sliders are persistent by default
>>>     help_text='Even Number with Markers',
>>>     required=False,
>>>     min_value=0,
>>>     max_value=10,
>>>     initial=6,
>>>     widget=MaterialSliderInput(
>>>         is_discrete=True,
>>>         display_markers=True,
>>>         attrs={
>>>             'step': '2',
>>>             },
>>>         ),
>>>     )

class material_widgets.widgets.MaterialSplitDateTimeWidget(attrs=None, date_format=None, time_format=None, label=None, date_label='Date', date_help_text='YYYY-MM-DD', date_persistent_help_text=False, time_label='Time', time_help_text='HH:MM:SS', time_persistent_help_text=False, *args, **kwargs)[source]¶

Material SplitDateTimeWidget

Splits datetime input into two MaterialTextFields. Default widget for SplitDateTimeField under MaterialForm.

Parameters:

label (str, optional) – Displayed to the left of the widget fields in the template. Defaults to widget’s capitalized field name with underscores converted to spaces.

Other Parameters:

attrs (dict, optional) – HTML attributes to be included in the multiwidget’s template.
date_format (str, optional) – Format to display initial field value. Defaults to first format found in Django’s DATE_INPUT_FORMATS.
time_format (str, optional) – Format to display initial field value. Defaults to first format found in Django’s TIME_INPUT_FORMATS.
label (str, optional) – Passes value through from field parameter.
date_label (str, optional) – Displayed on the Date widget’s field in the template. Defaults to ‘Date’.
date_help_text (str, optional) – Displayed under the Date input field. Defaults to ‘YYYY-MM-DD’.
date_persistent_help_text (bool, optional) – Help text for Date widget will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.
time_label (str, optional) – Displayed on the Time widget’s field in the template. Defaults to ‘Time’.
time_help_text (str, optional) – Displayed under the Time input field. Defaults to ‘HH:MM:SS’.
time_persistent_help_text (bool, optional) – Help text for Time widget will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> split_datetime = forms.SplitDateTimeField(
>>>     required=False,
>>>     widget=MaterialSplitDateTimeWidget(
>>>         date_label='Birthdate',
>>>         date_help_text='YYYY-MM-DD',
>>>         date_persistent_help_text=True,
>>>         time_label='Birthtime',
>>>         time_help_text='HH:MM:SS',
>>>         time_persistent_help_text=True,
>>>         ),
>>>     )

class material_widgets.widgets.MaterialSplitHiddenDateTimeWidget(attrs=None, date_format=None, time_format=None)[source]¶

Material SplitHiddenDateTimeWidget

Parameters:	initial (list or tuple of str, optional) – Initial values to populate the hidden date and time fields in the form.

Examples

>>> split_hidden_datetime = forms.SplitDateTimeField(
>>>     initial=['1965-08-09', '12:00:00'],
>>>     widget=widgets.SplitHiddenDateTimeWidget(),
>>>     )

class material_widgets.widgets.MaterialSwitchInput(label=None, help_text=None, *args, **kwargs)[source]¶

Material SwitchInput

Parameters:	label (str, optional) – Displayed to the left of the switch. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed as a tool tip on the label.

Examples

Declare widget explicity in a BooleanField to use widget.

>>> boolean_switch = forms.BooleanField(
>>>     label='Boolean Switch',
>>>     help_text='This is a switch',
>>>     widget=MaterialSwitchInput(),
>>>     )

class material_widgets.widgets.MaterialTextarea(persistent_help_text=False, *args, **kwargs)[source]¶

Material Textarea

Other Parameters:
Parameters:	label (str, optional) – Displayed in the widget’s field to the upper left of the box in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> textarea = forms.CharField(
>>>     label="Captain's Log",
>>>     help_text='Write as much as you want',
>>>     widget=widgets.MaterialTextarea(
>>>         persistent_help_text=True,
>>>         ),
>>>     )

class material_widgets.widgets.MaterialTextInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material TextInput

Default widget for CharField and various other fields under MaterialForm.

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> username = forms.CharField(
>>>     label='Choose a Username',
>>>     min_length=3,
>>>     max_length=32,
>>>     help_text='3-32 characters required',
>>>     widget=widgets.TextInput(
>>>         persistent_help_text=True,
>>>         attrs={
>>>             'autofocus': "autofocus",
>>>             },
>>>         ),
>>>     )

class material_widgets.widgets.MaterialTimeInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material TimeInput

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> time_field = forms.TimeField(
>>>     label='Time',
>>>     help_text='HH:MM:SS',
>>>     widget=MaterialTimeInput(
>>>         persistent_help_text=True,
>>>         ),
>>>     )

class material_widgets.widgets.MaterialURLInput(persistent_help_text=False, *args, **kwargs)[source]¶

Material URLInput

Default widget for URLField under MaterialForm.

Other Parameters:
Parameters:	label (str, optional) – Displayed on the widget’s field in the template. Defaults to widget’s capitalized field name with underscores converted to spaces. help_text (str, optional) – Displayed under the input field.
	persistent_help_text (bool, optional) – Help text will be persistently displayed if True, else it will only be visible when the field is active. Defaults to False.

Examples

Declare widget explicity to use custom widget parameters.

>>> url = forms.URLField(
>>>     label='URL',
>>>     help_text='Website',
>>>     initial='http://github.com/ooknosi',
>>>     widget=widgets.MaterialTextInput(
>>>         persistent_help_text=True,
>>>         ),
>>>     )