API reference

Template tags

Important

This section is for projects using Django’s default DjangoTemplates backend. For projects using Jinja2, see the Jinja2 functions section.

To use the following template tags, you’ll need to load this package’s custom template tag set in your templates like so:

{% load uswds_forms %}

fieldset

The {% fieldset %} tag can be used to render a form field using the <fieldset> element. The field’s label is also rendered, along with any associated form errors and help text.

Markup is also added to ensure that screen reader users will have an easy time navigating grouped lists of options.

Sample usage:

{% fieldset my_form.name %}
{% fieldset my_form.address %}
{% fieldset my_form.birthday %}

Jinja2 functions

Important

This section is for projects using Django’s Jinja2 backend. For projects using Django templates, see the Template tags section.

For details on how to register any of these functions with your Jinja2 environment, see Jinja2 setup (optional).

uswds_forms.fieldset(field)

Render the given bound field as a <fieldset>. The field’s label is also rendered, along with any associated form errors and help text.

Once added to a Jinja2 environment, this function can be used from Jinja2 templates like so:

{{ fieldset(my_form.name) }}
{{ fieldset(my_form.address) }}
{{ fieldset(my_form.birthday) }}

Form

class uswds_forms.UswdsForm

This is a subclass of django.forms.Form that provides some functionality for rendering USWDS forms. Its constructor takes the exact same arguments, but some defaults are changed:

• error_class defaults to uswds_forms.UswdsErrorList, so that errors are formatted nicely.
• label_suffix defaults to the empty string, since none of the USWDS example forms have colons after the label names.

as_fieldsets()

Like other convenience methods such as as_p() and as_table(), this method renders all the form’s fields as a series of <fieldset> elements.

Under the hood, this just iterates over the form’s fields and renders them via the fieldset template tag, so you can use that if you need more granular control over rendering.

Form fields

These fields use the same core field arguments as core Django.

class uswds_forms.UswdsDateField(**kwargs)

A django.forms.MultiValueField for a USWDS-style date. Its value normalizes to a Python datetime.date object.

For an example of how this looks in practice, see the USWDS date input example.

class uswds_forms.UswdsMultipleChoiceField(**kwargs)

This is just a django.forms.MultipleChoiceField that uses the UswdsCheckboxSelectMultiple widget.

We’ve provided this field for convenience because the usability of the default django.forms.SelectMultiple is so terrible that you’ll probably never want to use it. Burn your select tags!

Widgets

All of the following widgets work with the DjangoTemplates and Jinja2 form renderers.

class uswds_forms.UswdsCheckboxSelectMultiple

This subclass of django.forms.CheckboxSelectMultiple styles grouped checkboxes appropriately for USWDS.

You can use this in a django.forms.MultipleChoiceField to get a list of checkboxes instead of a <select multiple> element for your choices.

For an example of how this looks in practice, see the USWDS checkboxes example.

class uswds_forms.UswdsDateWidget

A django.forms.MultiWidget for a USWDS-style date, with separate number fields for date, month, and year.

This widget is used automatically by uswds_forms.UswdsDateField, so you probably won’t need to use it directly. However, it can be subclassed in case you need to customize it.

get_context(name, value, attrs)

Returns the context for the widget’s template. This returns a superset of what’s provided by its superclass’ get_context() implementation, adding the following keys to widget:

• 'hint_id': The unique id of some hint text showing users an example of what they can enter.
• 'subwidgets': This has the same iterable value described in the superclass documentation, but it has been enhanced such that its year, month, and day properties are aliases to its entries. Using these aliases can potentially make templates more readable.

template_name = 'uswds_forms/date.html'

This is the default template used by the widget, which can be overridden if needed.

class uswds_forms.UswdsRadioSelect

This subclass of django.forms.RadioSelect styles radio buttons appropriately for USWDS.

You can use this in a django.forms.ChoiceField to get a list of radio buttons instead of a <select> element for your choices.

For an example of how this looks in practice, see the USWDS radio buttons example.

Other utilities

class uswds_forms.UswdsErrorList

This is an error list formatter that renders errors in the style used by USWDS forms. For an example of how this makes errors look in practice, see the USWDS text inputs example.

Note that you probably don’t need to use this class directly, as UswdsForm uses it by default.

For more details on how to use this class, see the Django documentation on customizing the error list format.