python forms example - Django: How to build a custom form widget?

2 Answers

Django <1.11

Additionally to the other answers, this is a small code sample of a custom widget:

from django.forms.widgets import Widget
from django.template import loader
from django.utils.safestring import mark_safe

class MyWidget(Widget):
    template_name = 'myapp/my_widget.html'

    def get_context(self, name, value, attrs=None):
        return {'widget': {
            'name': name,
            'value': value,

    def render(self, name, value, attrs=None):
        context = self.get_context(name, value, attrs)
        template = loader.get_template(self.template_name).render(context)
        return mark_safe(template)


<textarea id="mywidget-{{ }}" name="{{ }}">
{% if widget.value %}{{ widget.value }}{% endif %}</textarea>

Django 1.11

Widgets are now rendered using the form rendering API.

widgets template errors

I am having a difficult time finding documentation on how to write a custom widget.

My questions are:

  • If I build a custom widget, can it be used equivalently for the admin interface or for normal forms?
  • If I want to allow the user to edit a list of items, what widget should I subclass? What methods of the widget do I need to override/implement?
  • What widget method is responsible for going from the user's input back to the data model?


Usually I start by inheriting from one of the existing widgets, add a new desired property and then modify a render method. Here's an example for a filterable select widget I implemented. The filtering is done via jquery mobile.

class FilterableSelectWidget(forms.Select):
    def __init__(self, attrs=None, choices=()):
        super(FilterableSelectWidget, self).__init__(attrs, choices)
        # choices can be any iterable, but we may need to render this widget
        # multiple times. Thus, collapse it into a list so it can be consumed
        # more than once.
        self._data_filter = {}

    def data_filter(self):
        return self._data_filter

    def data_filter(self, attr_dict):

    def render_option(self, selected_choices, option_value, option_label):
        option_value = force_text(option_value)
        if option_value in selected_choices:
            selected_html = mark_safe(' selected="selected"')
            if not self.allow_multiple_selected:
                # Only allow for a single selection.
            selected_html = ''
        # use self.data_filter
        filtertext = self.data_filter.get(option_value)
        data_filtertext = 'data-filtertext="{filtertext}"'.\
            format(filtertext=filtertext) if filtertext else ''
        return format_html('<option value="{0}"{1} {3}>{2}</option>',

Then in the views where I create a form, I'll set the data_filter for the field.

        some_form.fields["some_field"] = \
        some_form.fields["some_field"].widget.data_filter = \