django-tokenfield provides a form input that behaves like a normal text input, but allows arbitrary placeholder variables/tokens to be inserted at any position in the text. It’s inspired by Facebook’s message recipient input.


An example input containing tokens interspersed with text.


  1. Download and install django-tokenfield – pip install django-tokenfield
  2. Add django_tokenfield to INSTALLED_APPS in your project’s
  3. When rendering a form that contains a TokenField, ensure to include, jQuery, jQuery templating, and knockout.js.

The Widget

The widget handles translating the Python representation of a token string into HTML, JS, and CSS that the browser can render into an interactive input which is capable of sending back a suitably encoded representation of the user’s input.

In Django the Widget.render() method must be capable of accepting data in the following formats:

  • JSON string:

        {"type": "literal", "value": "abc"},
        {"type": "variable", "value": "firstName"},


    When does this occur?

  • Python token string representation:

    [<LiteralToken object>, <VariableToken object>, ...]
  • Junk string:


    A junk string may occur when a field is considered invalid, in which case the raw POST data is passed back to Widget.render() unmodified. The only situation when this would occur is if the JavaScript front-end is broken. The behaviour in these situations is to revert to an empty value.