In Django, what does a form or widget's inner Media class declare, and how does {{ form.media }} combine and order those assets?

## What Media declares Some widgets need front-end assets: a date picker's JavaScript, a colour picker's stylesheet, a donation amount slider. Django lets the Python class that renders the widget also **declare** those assets, through an inner `Media` class: ```python from django import forms class AmountSliderWidget(forms.NumberInput): class Media: css = {"all": ["donations/slider.css"]} js = ["donations/vendor/range.js", "donations/slider.js"] ``` - `css` is a dictionary from **media type** (`"all"`, `"screen"`, `"print"`, or a comma-separated list) to a list of stylesheet paths. - `js` is a list or tuple of script paths. - `extend` controls inheritance: by default a subclass's media is its parent's plus its own; `extend = False` drops the parent's, and a list such as `extend = ["css"]` keeps only those types. A `Form` can declare `Media` too, for assets that belong to the form rather than a widget, such as layout CSS. A dynamic `media` property can replace the static declaration when the assets depend on configuration. ## How a form combines its widgets' assets Every form has a `media` property whether or not it declares anything. It: 1. starts with an empty `Media` object; 2. adds `field.widget.media` for every field, in field order; 3. adds the form's own `Media` declaration; if that declaration sets `extend = False`, the widgets' assets are dropped and only the form's own remain. Adding `Media` objects **merges** their lists rather than concatenating them: - a path that appears in several lists is output once; - the relative order in which each list declared its files is preserved, so a library that two widgets both list before their own script is emitted before both scripts; - if two lists demand opposite orders — one says `a.js` then `b.js`, the other `b.js` then `a.js` — Django emits a **`MediaOrderConflictWarning`** and falls back to a simple de-duplicated order. ## Rendering the tags `{{ form }}` renders fields only; the page template must ask for the assets: ```django <head> {{ form.media.css }} </head> <body> <form method="post">{% csrf_token %}{{ form }}<button>Donate</button></form> {{ form.media.js }} </body> ``` | expression | output | |---|---| | `{{ form.media }}` | every `<link rel="stylesheet">` then every `<script>` | | `{{ form.media.css }}` | only the stylesheet links | | `{{ form.media.js }}` | only the script tags | A formset's `media` is the media of its first form (or of `empty_form` when there are none), and the admin renders `Media` for every widget it uses, which is why custom admin widgets declare it. ## How paths become URLs - A path starting with `http://`, `https://` or `/` is used as written. - Any other path is passed through Django's `static()` helper, so it gains `STATIC_URL` and, with a hashing storage, the hashed file name. Collecting and serving those files is the static files layer's job. ## Attributes on the tags Plain strings render bare `<script src>` and `<link href>` tags. To add attributes, use asset objects: - `forms.Script("donations/slider.js", defer=True)` — Django 5.2+; - `forms.Stylesheet("donations/print.css", media="print")` — Django 6.1+. ```python from django import forms class AmountSliderWidget(forms.NumberInput): class Media: js = [forms.Script("donations/slider.js", defer=True)] ``` Two assets with the same path but different attributes are treated as different entries when merging, so keep attributes consistent across widgets that share a file. ## Dynamic media When the assets depend on configuration, define a `media` property instead of an inner class; it must return a `forms.Media` object: ```python from django import forms from django.conf import settings class AmountSliderWidget(forms.NumberInput): @property def media(self): theme = getattr(settings, "DONATION_THEME", "light") return forms.Media(css={"all": [f"donations/slider-{theme}.css"]}, js=["donations/slider.js"]) ``` `DONATION_THEME` here is a project setting of your own, not a Django one. A property replaces the declarative merge with the parent class, so add `super().media` yourself if the parent's assets are still needed. ## Common mistakes - Expecting `{{ form }}` to include the assets, then wondering why a widget is unstyled. - Rendering `{{ form.media }}` once per form on a page with several forms, loading shared libraries twice — add the `Media` objects (`form_a.media + form_b.media`) and render the sum once. - Hard-coding `/static/...` in `Media`, which bypasses `static()` and breaks hashed file names.