Widgets

The widgets below provide example renderings using these enums:

class Color(Enum):

    RED   = 'R'
    GREEN = 'G'
    BLUE  = 'B'

class Permissions(IntFlag):

    READ    = 1 << 0
    WRITE   = 1 << 1
    EXECUTE = 1 << 2

Django’s builtin Select widget is the default widget used for EnumField fields. It renders a simple drop down select box. For example:

class Model(models.Model):
    color = EnumField(Color, default=Color.RED)

Model.objects.create()

class django_enum.forms.NonStrictSelect(attrs=None, choices=())

Bases: NonStrictMixin, Select

This is the default widget used for EnumField fields that have strict set to False.

This widget will render a drop down select field that includes an option for each value on the enumeration, but if the field is set to a value outside of the enumeration it will be included and selected in the drop down:

For example, using our Color enumeration:

class Model(models.Model):
    color = EnumField(Color, strict=False, max_length=12)

Model.objects.create(color="YELLOW")

class django_enum.forms.NonStrictSelectMultiple(attrs=None, choices=())

Bases: NonStrictMixin, SelectMultiple

This widget will render a multi select box that includes an option for each value on the enumeration and for any non-value that is passed in.

class django_enum.forms.FlagSelectMultiple(enum: Type[Flag] | None = None, **kwargs)

Bases: FlagMixin, SelectMultiple

This is the default widget used for FlagField fields.

This widget will render IntFlag types as a multi select field with an option for each flag value. Values outside of the enumeration will not be displayed.

For example, using our Permissions enumeration:

class Model(models.Model):
    permissions = EnumField(Permissions)

Model.objects.create(permissions=Permissions.READ | Permissions.EXECUTE)

class django_enum.forms.FlagCheckbox(enum: Type[Flag] | None = None, **kwargs)

Bases: FlagMixin, CheckboxSelectMultiple

This widget will render IntFlag types as checkboxes with a checkbox for each flag value.

For example, using our Permissions enumeration:

class Model(models.Model):
    permissions = EnumField(Permissions)

Model.objects.create(permissions=Permissions.READ | Permissions.EXECUTE)

class django_enum.forms.NonStrictFlagSelectMultiple(enum: Type[Flag] | None = None, **kwargs)

Bases: NonStrictFlagMixin, FlagSelectMultiple

This widget will render a multi select box that includes an option for each flag on the enumeration and also for each bit lot listed in the enumeration that is set on the value.

Options for extra bits only appear if they are set. You should pass choices to the form field if you want additional options to always appear.

class Model(models.Model):
    permissions = EnumField(Permissions, strict=False)

Model.objects.create(
    permissions=Permissions.READ | Permissions.EXECUTE | ( 1 << 4 )
)

class django_enum.forms.NonStrictFlagCheckbox(enum: Type[Flag] | None = None, **kwargs)

Bases: NonStrictFlagMixin, FlagCheckbox

This widget will render a checkbox for each flag on the enumeration and also for each bit not listed in the enumeration that is set on the value.

Checkboxes for extra bits only appear if they are set. You should pass choices to the form field if you want additional checkboxes to always appear.

For example, using our Permissions enumeration:

class Model(models.Model):
    permissions = EnumField(Permissions, strict=False)

Model.objects.create(
    permissions=Permissions.READ | Permissions.EXECUTE | ( 1 << 4 )
)

class django_enum.forms.NonStrictRadioSelect(attrs=None, choices=())

Bases: NonStrictMixin, RadioSelect

This widget will render a radio button select field that includes an option for each value on the enumeration, but if the field is set to a value outside of the enumeration it will be included and selected:

For example, using our Color enumeration:

class Model(models.Model):
    color = EnumField(Color, strict=False, max_length=12)

Model.objects.create(color="YELLOW")

Mixins

class django_enum.forms.NonStrictMixin

Mixin to add non-strict behavior to a widget, this makes sure the set value appears as a choice if it is not one of the enumeration choices.

render(*args, **kwargs)

Before rendering if we’re a non-strict field and our value is not one of our choices, we add it as an option.

class django_enum.forms.FlagMixin(enum: Type[Flag] | None = None, **kwargs)

This mixin adapts a widget to work with IntFlag types.

__init__(enum: Type[Flag] | None = None, **kwargs)

format_value(value)

Return a list of the flag’s values, unpacking it if necessary.

class django_enum.forms.NonStrictFlagMixin

Mixin to add non-strict behavior to a multiple choice flag widget, this makes sure that set flags outside of the enumerated flags will show up as choices. They will be displayed as the index of the set bit.

render(*args, **kwargs)

Before rendering if we’re a non-strict flag field and bits are set that are not part of our flag enumeration we add them as (integer value, bit index) to our (value, label) choice list.