Skip to content

Installation

Five steps: install the package, configure Django, install the icons, build the CSS, and load htmx and Alpine.js for the dynamic widgets.

1. Install the package

pip install django-formwork

Or with uv:

uv add django-formwork

2. Configure Django

Add django.forms, django_iconx (a dependency that manages the icon set) and django_formwork to your installed apps, set the form renderer, and make sure you have a project-level static directory:

# settings.py
INSTALLED_APPS = [
    ...,
    "django.contrib.staticfiles",
    "django.forms",
    "django_iconx",
    "django_formwork",
]

# Every form renders through the formwork templates
FORM_RENDERER = "django_formwork.FormworkRenderer"

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
        ...
    },
]

STATICFILES_DIRS = [BASE_DIR / "static"]

FormworkRenderer is a TemplatesSetting renderer: it loads templates through TEMPLATES, so a project template with the same path overrides any formwork template. "django.forms" supplies Django's own widget templates, and the DjangoTemplates backend must find app templates (APP_DIRS=True or the app_directories loader). django_iconx must be in INSTALLED_APPS for the next step to work. STATICFILES_DIRS tells the icon install where to put the downloaded files and lets Django serve them.

On startup, formwork imports the forms module of every installed app, so a form with a server-side search registers it before the first request.

manage.py check reports two setup mistakes: django_formwork.E001 when a form declares a server-side search but the URLconf does not include django_formwork.urls, and django_formwork.E002 when "django.forms" is missing from INSTALLED_APPS.

3. Install the icons

Formwork's widgets use Lucide icons, fetched at setup time rather than bundled. Run:

python manage.py formwork install

The command downloads the Lucide SVGs through django-iconx into <first STATICFILES_DIRS entry>/icons/lucide/. Then it generates iconx/icons.css in your static directory, with one CSS class per icon that points at the served SVG.

A second run downloads and generates the files again in place. Both output directories (static/icons/ and static/iconx/) are generated artifacts: gitignore them and run formwork install in CI and on fresh checkouts, or commit them if you prefer vendoring.

Command reference: formwork install

python manage.py formwork install [--output DIR]
  • --output DIR: directory to write the generated CSS into (the file lands at DIR/iconx/icons.css). By default the command resolves your project static directory: the first entry of STATICFILES_DIRS if set, otherwise BASE_DIR/static. Use --output when your CSS build inputs live elsewhere.

The icon SVGs always go into the first STATICFILES_DIRS entry, because django-iconx downloads them there, so --output moves only the generated CSS. Without STATICFILES_DIRS the command uses BASE_DIR/static and prints a warning; add that directory to STATICFILES_DIRS, or Django does not serve the icons. With neither setting, the command stops with an error.

4. Build the CSS

Formwork uses DaisyUI 5 for component styling and Tailwind CSS 4+ for the build step. Formwork ships formwork.css, the Tailwind source. It contains @apply directives, @import "tailwindcss" and the DaisyUI @plugin, so build it with the Tailwind CLI or the PostCSS plugin, and import neither Tailwind nor DaisyUI a second time next to it.

Install the build tools:

npm install -D tailwindcss @tailwindcss/cli daisyui@5

Create your Tailwind input (say app.css in your project root):

/* Formwork's Tailwind source (already includes Tailwind + the DaisyUI plugin). */
@import "path/to/site-packages/django_formwork/static/formwork/formwork.css";

/* The icon classes generated by `manage.py formwork install` (step 3).
   In a layer, so that size-* utilities override the 1em icon size. */
@import "./static/iconx/icons.css" layer(components);

/* Your own templates. */
@source "./templates/";

Tailwind 4 only emits utility classes it finds in scanned sources. formwork.css registers the package templates, widgets and scripts with @source itself, and it safelists the {select,input,textarea}-{color} and badge-{color} classes, so your entry point lists only your own sources. Add an @source or an @source inline(...) for a class name that your code builds at render time, such as f"badge-{status}".

To find the site-packages path for the import line:

python -c "import django_formwork; print(django_formwork.__path__[0])"

Then build:

npx @tailwindcss/cli -i app.css -o static/dist.css

And link the built file in your base template:

{% load static %}
<link rel="stylesheet" href="{% static 'dist.css' %}">

The examples/full app in the repository is a working copy of exactly this setup.

DaisyUI version

Formwork requires DaisyUI 5. DaisyUI 4 and earlier use a different component API and do not work with formwork. The CI builds the CSS with the DaisyUI 5 release pinned in the repository's package-lock.json.

5. htmx and Alpine.js

The dynamic widgets (dropdowns, server-side search, password reveal, steppers, drop zones, validated textarea) need htmx 4, htmx's alpine-compat extension and Alpine.js 3. Load them yourself, in this order:

{% load formwork %}
<script src="https://unpkg.com/htmx.org@4.0.1/dist/htmx.min.js"></script>
<script src="https://unpkg.com/htmx.org@4.0.1/dist/ext/hx-alpine-compat.min.js"></script>
{% formwork_js %}
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
  1. htmx comes first, because the formwork modules register htmx extensions.
  2. The alpine-compat extension comes after htmx. It is required: without it a morph strips what Alpine bindings (x-show, x-text, :class, :aria-selected) wrote into the DOM.
  3. {% formwork_js %} comes before Alpine. Module scripts and defer scripts run in document order, and each formwork module registers its component in an alpine:init listener, which must exist when Alpine starts.

htmx 4 sends the server-side search and validation requests, and its built-in outerMorph swap morphs a re-rendered form into the page. {% formwork_js %} loads formwork.js as an ES module, which imports formwork-core.js (the formwork-morph htmx extension, dirty-field tracking, and native-validation disabling) plus each widget's Alpine.data component.

htmx extensions

htmx 4 runs every registered extension on the whole page. If you restrict them with an htmx.config.extensions whitelist, list alpine-compat and formwork-morph, plus formwork-sections on a page that loads section forms.

formwork-core.js adds open to htmx.config.morphIgnore, so a morph leaves an open dropdown or disclosure as the user left it. For the same reason a server response cannot open or close a <details> or a <dialog> by morph; change the open state in the browser.

JS loading paths

The {% formwork_js %} bundle is one tag and loads the core and every widget component. Two other paths load the same files.

For per-form loading via Django's Media, use {{ form.media }} for the widget JS the form actually contains, and add {% formwork_core_js %} for the page-global core (morph, dirty-tracking, validation disabling). Select, SelectMultiple, ComboBox, DatePicker, StepperNumberInput, PasswordInput, SearchInput, FileDropzoneInput, ImageDropzoneInput, InputMask and ValidatedTextarea each declare a Media class that points at their Alpine component file. Place both tags where {% formwork_js %} would go, before Alpine.

For a JS bundler (vite, webpack or esbuild), import formwork.js by its file path in the installed package, under the directory that the command in step 4 prints: import "path/to/site-packages/django_formwork/static/formwork/formwork.js";. The bundler follows the relative imports and emits one bundle, so the page needs no formwork template tag. The bundle must run after htmx and before Alpine, like the tag.

ES modules are deduplicated by URL, so mixing tags is harmless. Combining {% formwork_js %} and {% formwork_core_js %} on the same page still executes the core only once.

{% formwork_sections_js %} loads sections.js for section forms. The bundle leaves it out. Load it after htmx; it does not need Alpine.

Translations

Every string that formwork shows (placeholders, button labels, the "N selected" counts, error messages) goes through Django's translation machinery. Formwork ships no message catalog: run makemessages in your project to collect the strings and translate them there. The JavaScript reads its translated texts from data-* attributes that the templates render, so the pages need no JavaScript catalog either.