Tag Options

Model options define how a tag model behaves. They can either be set in the model field arguments, or in the tag model's TagMeta class. Once defined, they are then stored in a TagOptions instance on the tag model, accessible at MyTagModel.tag_options (and shared with tag model fields at MyTaggedModel.tags.tag_options).

Tagulous only lets you set options for a tag model in one place - if you use a custom model you must set options using TagMeta, and if you share an auto-generated model between fields, only the first field can set options.

Form options are a subset of the model options, and are also used to control tag form fields, and are also stored in a TagOptions instance. If the field is part of a ModelForm it will inherit options from the model, otherwise options can be passed in the field arguments.

Model Options

The tag model options are:


List of initial tags for the tag model. Must be loaded into the database with the management command initial_tags.

Value can be a tag string to be parsed, or an array of strings with one tag in each string.

To change initial tags, you can change the initial option and re-run the command initial_tags.

You should not find that you need to update initial regularly; if you do, it would be better to use the Tagulous admin tools to add tags to the model directly.

If provided as a tag string, it will be parsed using spaces and commas, regardless of the space_delimiter option.

Default: ''


The protected state for any tags created by the initial argument - see Protected tags.

Default: True


Whether all tags with count 0 should be protected from automatic deletion.

If false, will be decided by tag.protected - see Protected tags.

Default: False


If True, tags will be case sensitive. For example, "django, Django" would be two separate tags.

If False, tags will be capitalised according to the first time they are used.

Note when using sqlite: substring matches on tag names, and matches on tag names with non-ASCII characters, will never be case sensitive - see the databases django documentation for more information.

See also force_lowercase

Default: False


Force all tags to lower case

Default: False


TagField only - this is not supported by SingleTagField.

Specifies the maximum number of tags allowed.

Set to 0 to have no limit.

If you are setting it to 1, consider using a SingleTagField instead.

Default: 0


TagField only - this is not supported by SingleTagField.

If True, both commas and spaces can be used to separate tags. If False, only commas can be used to separate tags.

Default: True


Field argument only - this cannot be set in TagMeta

If True, slashes in tag names will be used to denote children, eg grandparent/parent/child, and these relationships can be traversed. See Tag Trees for more details.

If False, slashes in tag names will have no significance, and no tree properties or methods will be present on tag objects.

Default: False


If True, override all other autocomplete settings and use the tags defined in the initial argument for autocompletion, embedded in the form field HTML.

For more advanced autocomplete filtering options (ie filter tags by user), see the example Filtering autocomplete by related fields.

Default: False


Specify the view to use for autocomplete queries.

This should be a value which can be passed to Django's reverse(), eg the name of the view.

If None, all tags will be embedded into the form field HTML as the data-autocomplete attribute.

If this is an invalid view, a ValueError will be raised.

Default: None


Maximum number of tags to provide at once, when autocomplete_view is set.

If the autocomplete adaptor supports pages, this will be the number shown per page, otherwise any after this limit will not be returned.

If 0, there will be no limit and all results will be returned

Default: 100



Default: None


A shortcut for defining a get_absolute_url method on the tag model. Only used when defined in tag fields which auto-generate models.

It is common to need to get a URL for a tag, so rather than converting your tag field to use a custom TagModel just to implement a get_absolute_url method, you can pass this argument a callback function.

The callback function will be passed the tag object, and should return the URL for the tag. See the Tag URL example for a simple lambda argument.

If not set, the method get_absolute_url will not be available and an AttributeError will be raised.

Default: None

verbose_name_singular, verbose_name_plural

When a tag model is auto-generated from a field, it is given a verbose_name based on the tagged model's name and the tag field's name; the verbose_name_plural is the same, but with an added s at the end. This is primarily used in the admin.

However, this will sometimes not make grammatical sense; these two arguments can be used to override the field name component of the model name.

The verbose_name_singular will usually be used with a TagField - for example, the auto-generated model for MyModel.tags will have the singular name My model tags; this can be corrected by setting verbose_name_singular="tag" in the field definition.

The verbose_name_plural will usually be used with a SingleTagField - for example, the auto-generated model for MyModel.category will have the plural name My model categorys; this can be corrected by setting verbose_name_plural="categories" in the field definition.

If one or both of these are not set, Tagulous will try to find the field name from its verbose_name argument, falling back to the field name.

Form Options

The following options are used by form fields:

The TagOptions Class

The TagOptions class is a simple container for tag options. The options for a model field are available from the tag_options property of unbound tagulous.models.SingleTagField or tagulous.models.TagField fields.

All options listed in Model Options are available directly on the object, except for to. It also provides two instance methods:


Get a dict of all options

If with_defaults is true, any missing settings will be taken from the defaults in constants.OPTION_DEFAULTS.


Get a dict of just the options for a form field.

If with_defaults is true, any missing settings will be taken from the defaults in constants.OPTION_DEFAULTS.


initial_tags = MyModel.tags.tag_options.initial
if "force_lowercase" in MyModel.tags.tag_options.items():

TagOptions instances can be added together to create a new merged set of options; note though that this is a shallow merge, ie the value of autocomplete_settings on the left will be replaced by the value on the right:

merged_options = TagOptions(
    autocomplete_settings={'width': 'resolve'}
) + TagOptions(
    autocomplete_settings={'allowClear': True}
# merged_options.autocomplete_settings == {'allowClear': True}

In the same way, setting autocomplete_settings on the field will replace any default value.