Advanced integration
Search inside the Combobox popup
With local options, trigger_label enables a Kumo-style button trigger and search inside the popup. value selects the native option value; display_label optionally shortens the trigger. Filtering ignores case and accents, disabled choices cannot be selected, and native form values/reset remain available. trigger_variant=ghost changes the trigger appearance. Supply an endpoint to retain input-based HTMX search.
languages = [{"value": "en", "label": "English"}, {"value": "cs", "label": "Čeština"}]{% load wdj %}{% include "wdj/components/combobox.html" with id="language" name="language" options=languages value="en" trigger_label="Select a language" only %}Localized Combobox and Autocomplete
Pass caller-owned labels for search_placeholder, list_label, empty_message, required_message and remove_label. An explicit placeholder overrides search_placeholder. Local empty results use empty_message; an HTMX endpoint translates its own empty fragment. Multiple values submit as CSV and require an actual selection. Initial and newly selected chips preserve remove_label after native form reset and HTMX mounting. All supplied text is escaped.
labels = { "search_placeholder": "Caută un mediu…", "list_label": "Medii disponibile", "empty_message": "Niciun rezultat", "required_message": "Selectează cel puțin o opțiune.", "remove_label": "Elimină",}options = [{"value": "prod", "label": "Production"}, {"value": "stage", "label": "Staging"}]{% load wdj %}{% include "wdj/components/combobox.html" with name="environments" label="Medii" labels=labels options=options multiple=True required=True only %}Runtime and state ownership
Load the local HTMX asset, wdj.js, then Alpine.js with defer. wdj.js registers wdjSelect, wdjCalendar, wdjTabs, wdjSidebar and wdjChart before Alpine starts. Django owns data, permissions and validation. A replaced HTMX root resets its local state; a stable parent retains it. Fragment responses use Cache-Control: no-store and Vary: HX-Request.
Custom Select with native form values
The styled Alpine popup is the default. Use mode=native for an explicit browser picker; it also remains the no-JavaScript fallback. The popup supports rich descriptions, icons, groups, disabled rows, multiple selection, typeahead and keyboard navigation. Its native select submits the values and handles reset. options is a list of value/label dictionaries; a group has label/options. Multiple selection uses a selected flag per option. Native manual popovers place the options above clipped and transformed containers. Choose stable unique IDs. align_selected centers the current option when viewport space permits.
options = [ {"value": "prod", "label": "Production", "icon": "globe", "description": "Public application"}, {"value": "stage", "label": "Staging"}, {"value": "dev", "label": "Development", "disabled": True},]{% load wdj %}<form method="post"> {% csrf_token %} {% include "wdj/components/select.html" with id="environment" mode="custom" name="environment" label="Environment" options=options selected="stage" required=True only %} {% include "wdj/components/button.html" with label="Save" type="submit" only %} {% include "wdj/components/button.html" with label="Reset" type="reset" only %}</form>Calendar and native date inputs
DatePicker dates/datetimes and DateRangePicker default to the styled wdj popup. Use display=calendar for inline rendering or display=native for explicit browser controls; time/month retain native controls. The editable ISO field and single icon trigger never invoke a native date popup. calendar.html also remains available directly. Datetime selection preserves the time, with a time control inside the popup. Weeks start on Sunday by default; fixed_weeks=True keeps six rows. Alt+ArrowDown opens the popup from the field. calendar_mode is single, multiple or range on DatePicker; DateRangePicker selects a range and submits start_name/end_name separately. Native date/time/month fields validate ISO format, min/max and step when an engine falls back to text; time bounds can cross midnight. Values use ISO dates or CSV. locale controls month/day names, week_starts_on is 0 (Sunday, default) to 6, and number_of_months is bounded to 1-12 with responsive wrapping. min/max, disabled_dates and inclusive min_days/max_days constraints apply to typed values and calendar selections. Editable CSV fields enforce required and range completeness; validate all values again in Django. labels overrides escaped action and validation text: previous_month, next_month, open_calendar, calendar_label, navigation, selected_dates, time, invalid_date, unavailable, incomplete_range, single_date, range_length and blocked_range. trigger_label takes precedence over open_calendar. presets accepts a list of label/start/end dictionaries or True for the last 7/30/90 days.
{% load wdj %}{% include "wdj/components/calendar.html" with id="period" name="period" label="Reporting period" mode="range" month="2026-10" min="2026-10-01" max="2026-12-31" min_days=3 max_days=14 disabled_dates=blocked_dates presets=presets error=period_error only %}# Django contextblocked_dates = ["2026-10-15"]presets = [{"label": "First week", "start": "2026-10-01", "end": "2026-10-07"}]Directed Flow diagrams
Use unique node keys. Edges refer to source/target keys with optional left/right/top/bottom anchors. Flat nodes form a sequence. columns contains nodes lists, or branches containing their own nodes lists. Node descriptions, icons, links, disabled state and dot shapes are supported. Connectors remeasure on resizing and node mutation; the viewport supports native touch scrolling, keyboard scrolling and mouse panning.
nodes = [{"key": "receive", "label": "Receive", "icon": "download"}, {"key": "validate", "label": "Validate", "description": "Check the request"}, {"key": "save", "label": "Save"}]edges = [{"source": "receive", "target": "validate"}, {"source": "validate", "target": "save"}]{% load wdj %}{% include "wdj/components/flow.html" with id="request-flow" label="Request pipeline" nodes=nodes edges=edges only %}Offline maps and globe
Build data with wdj.maps.map_data. Supply kind=bubble, choropleth or globe; country values use Natural Earth ISO three letter codes. Each marker has name, longitude, latitude and optional value. Geometry is local public domain Natural Earth data. No map API, token or network request is needed. Flat maps use a fitted Mercator projection and support bounded zoom/pan with buttons, drag and keyboard. Markers accept bounded radius, color (hex or wdj token) and description. Pointer/focus tooltips show details. Globe horizon clipping still differs from Kumo. The map emits wdj:map-select. Auto rotation pauses while focused, hidden or under reduced motion.
from wdj.maps import map_datamap_state = map_data([ {"name": "London", "longitude": -0.12, "latitude": 51.5, "value": 900},], {"GBR": 40, "FRA": 30}, kind="globe"){% load wdj %}{% include "wdj/components/map.html" with id="locations" label="Application locations" data=map_state draggable=True auto_rotate=False only %}LayerDialog and rich slots
layer_dialog.html supplies a layered native modal and separate action footer. Drawer opens at any of the four edges, supports dismiss_disabled and a localized close_label; focus returns to its trigger in Chromium, Firefox and WebKit. Native dialog keeps focus inside the modal and returns focus to its trigger. dismiss_disabled prevents Escape/backdrop dismissal; a pending operation must supply its own completion action. wdj:dialog-close supports caller cleanup. Keep dialogs mounted. The component template receives explicit parameters; the captured block body renders with the caller context. Pass extra parameters when nested component templates need them.
{% load wdj %}{% wdj_component "wdj/components/layer_dialog.html" id="edit-profile" title="Edit profile" trigger_label="Edit profile" profile_name=profile_name %} <form method="post"> {% csrf_token %} {% include "wdj/components/input.html" with name="name" label="Name" value=profile_name only %} {% include "wdj/components/button.html" with label="Save" type="submit" only %} </form>{% endwdj_component %}Charts and external legends
ECharts loads only when page_has_charts is set. Supply chart options from wdj.charts or an application dictionary. An external legend targets the chart's unique ID; names must match series names. It toggles real series, highlights on hover/focus and stays synchronized with the chart legend. Changing theme preserves selected series. wdj:chart-click and wdj:chart-legend-change expose events for application handlers; custom options need JSON serializable values.
{% load wdj %}{% include "wdj/components/chart.html" with id="requests-chart" option=chart_option only %}{% include "wdj/components/chart_legend.html" with target="requests-chart" items=legend_items only %}# Django contextlegend_items = [{"name": "Requests", "value": "1,204", "color": "#2563eb"}]Highlighted code and copy
code_highlighted.html uses the free Pygments parser on the server, preserving multiline grammar state and escaping each token before rendering. Language aliases, line numbers and selected lines are supported; unknown languages stay escaped plain text. Colors use wdj tokens rather than Shiki themes. Supply copy_label for localization, plain=True to disable coloring, and highlight_lines as a comma separated list or range. Never mark untrusted code safe.
{% load wdj %}{% include "wdj/components/code_highlighted.html" with code=example_source lang="python" filename="views.py" line_numbers=True highlight_lines="2-4" copy_label="Copy source" only %}Complete API and verification
Every catalog page includes its actual template parameters and copyable examples. The JSON registry exposes the same API. Tabs, sliders, accordions, grouped navigation and eight reusable blocks have dedicated examples. Browser checks cover both themes, narrow/landscape layouts, keyboard, touch, repeated swaps and axe critical/serious violations. Automated coverage runs in Chromium, Firefox and WebKit with narrow/desktop viewports. WebKit automation is not certification of installed Safari or physical devices.