• Silence warnings about multiple root elements for direct views.

  • Handle force_render in nested children for direct views #663.

  • Handle error when manually refreshing direct views.

  • Handle component field type annotations for dataclasses and Pydantic BaseModel #649 by siliconcow.

  • Update startunicorn command to prevent spamming users and handle folder creation for nested components #642 by felipmartins.

Breaking changes

  • Unparseable kwarg argument passed into a component will be considered None instead of being converted to a string.

<!-- If `abcde` is not a variable in the template context, it will get set to `name` as `None` whereas before it would get set as 'abcde' -->
{% unicorn 'hello' name=abcde %}


  • Update logic to find components #655 by jacksund.

  • Add fallback location to look for components.


  • Try to prevent type hints from crashing components. #639


This release could not have been made possible without the generous support of and Thank you for sponsoring me and believing in django-unicorn! It also includes critical improvements to nested components from

  • Handle a list of ValidationError or just a string instead of requiring a the dict version.

  • Better support for type annotations for component fields.

  • Improved nested component support by imankulov.

  • Add force_render and $parent.

Breaking changes

Child components will not by default render the parent component anymore. If this is required for your child component, specify self.parent.force_render = True in any action that requires the parent to re-render. This change will reduce network bandwidth and isolates the amount of re-rendering required for nested components.


  • Fix: Correctly serialize forms that have a a field with a Select widget.


  • Warn if there is a missing root element.

  • Use unicorn:id to merge elements with morphdom.


  • Handle Alpine.js being loaded with defer.


  • Add support for using both Alpine.js and Unicorn together in a component (#597 by imankulov).

  • Do not send a 304 if the child has a parent (#595).

  • Prevent sending the child DOM if there is a parent to reduce network payload size.

  • More verbose error message when a component can not be loaded (#453 by nerdoc).


Breaking changes


  • Coerce type annotated arguments in an action method to the specified type (#571).

  • Fix: Dictionary fields would sometimes create checksum errors (#572).


  • Support passing arguments into a component (#560).

  • Fix the handling of None for select elements. (#563).

  • Better handling of AuthenticationForm when used in Component.form_class (#552) by lassebomh.


  • Use CSRF_COOKIE_NAME Django setting (#545) by frnidito.

  • Asterisk wildcard support for targeting loading (#543) by regoawt.



  • Support more than 1 level of nested children (#476 by bazubii).

All changes since 0.49.2.


  • Fix: Calling methods with a model typehint would fail after being called multiple times (#476 by stat1c-void).

All changes since 0.49.1.


  • Fix: Missing pp import in Python 3.7.

All changes since 0.49.0.


  • Fix: Handle inherited (i.e. subclassed) models #459.

  • Fix: Support abbreviated u:view (#464 by nerdoc).

  • Add version and build date to minified JavaScript for easier debugging.

All changes since 0.48.0.


All changes since 0.47.0.


  • Fix: Include stacktrace for AttributeError errors.

  • Fix: Only call updated_ and updating_ component functions once.

All changes since 0.46.0.


  • Support for loading nested components from a route that uses a class-based view.

  • Better support for children components.

All changes since 0.45.1.


  • Fix: Handle JavaScript error that sometimes happens with nested components. 237 by clangley

All changes since 0.45.0.


  • Add ability to render initial data JavaScript inside the rendered component with SCRIPT_LOCATION setting

All changes since 0.44.1.


  • Fix: Some types of type annotations on a component method would cause an error when it was called #392 by nerdoc.

  • Add component_id, component_name, component_key to the unicorn dictionary in the template context #389 by nerdoc.

All changes since 0.44.0.


  • Add support for raising a ValidationError from component methods.

All changes since 0.43.1.


  • Fix: direct views were not caching the component correctly.

All changes since 0.43.0.


  • Defer displaying messages when an action method returns a redirect.

  • Prevent morphing or other changes when redirecting.

All changes since 0.42.1.


  • Fix: dictionaries in a component would generate incorrect checksums and trigger a Checksum does not match error

  • Remove some serializations that was happening unnecessarily on every render.

  • Add Python 3.10 and Django 4.0 to test matrix.

All changes since 0.42.0.


  • Remove all blank spaces from JSON responses.

  • Optional support for minifying response HTML with htmlmin.

  • Log warning message if the component HTML does not appear to be well-formed (i.e. an element does not have an ending tag). #342 by liamlawless35

Breaking changes

  • Bump supported Python to >=3.7.

All changes since 0.41.2.


  • Fix: Handle excluding a field’s attribute when the field is None.

All changes since 0.41.1.


  • Fix: Handle component classes with a bool class attribute and a form_class with a BooleanField. Reported by zurtri

All changes since 0.41.0.


  • Support using a context variable for a component name. #314 by robwa

All changes since 0.40.0.


All changes since 0.39.1.


  • Prefer prefetch_related to reduce database calls for many-to-many fields.

All changes since 0.39.0.


  • Explicit error messages when an invalid component field is excluded

  • Better support for serializing many-to-many fields which have been prefetched to reduce the number of database calls

  • Support excluding many-to-many fields with javascript_exclude

All changes since 0.38.1.


  • Fix: Allow components to be pickled so they can be cached.

All changes since 0.38.0.


  • Include request context in component templates.

All changes since 0.37.2.


  • Fix: nested field attributes for javascript_exclude.

All changes since 0.37.1.


  • Support nested field attributes for javascript_exclude.

All changes since 0.37.0.


  • Revert loading and dirty elements when the server returns a 304 (not modified) or a 500 error.

All changes since 0.36.1.


  • More verbose error messages when components can’t be loaded (nerdoc).

  • More complete handling to prevent XSS attacks.

All changes since 0.36.0.


  • Security fix: for CVE-2021-42053 to prevent XSS attacks (reported by Jeffallan).

Breaking changes

  • responses will be HTML encoded going forward (to explicitly opt-in to previous behavior use safe)

All changes since 0.35.3.


All changes since 0.35.2.


  • Fix: Make sure visible:elements trigger as expected in more cases.

  • Prevent the visible element from continuing to trigger if the visibility element method returns False.

All changes since 0.35.0.


  • Trigger an input or blur event for a model element from JavaScript.

  • Visibility event with unicorn:visible attribute.

Breaking changes

  • db_model Python decorator, unicorn:db, unicorn:field, unicorn:pk template attributes are removed.

All changes since 0.34.0.


  • Initial prototype for component template lifecycle events.

  • Fix: elements after a child component would not get initialized #262 by joshiggins.

  • Fix: cache would fail in some instances 258.

All changes since 0.33.0.


  • Fix: Allow comments, blank lines, or text at the top of component templates before the root element.

All changes since 0.32.0.


  • Add debounce support to actions.

All changes since 0.31.0.


  • Move JavaScript static assets into unicorn sub-folder

  • Determine correct path for installed app passed to startunicorn management command

  • Call startapp management command if app is not already installed

All changes since 0.30.0.


  • Look in all INSTALLED_APPS for components instead of only in a unicorn app 210

  • Support settings.APPS_DIR which is the default for django-cookiecutter instead of just settings.BASE_DIR 214

Breaking changes

  • Require an application name when running the startunicorn management command for where the component should be created

All changes since 0.29.0.


  • Sanitize initial JSON to prevent XSS

All changes since 0.28.0.


All changes since 0.27.2.


  • Fix bug with relationship fields on a Django model

All changes since 0.27.1.


  • Fix some issues with many-to-many fields on a Django model

All changes since 0.27.0.


  • Many-to-many fields on a Django model are now supported

  • Multiple partial targets

All changes since 0.26.0.


  • Completely redesigned and much improved support for Django models and QuerySets.

  • Fix the startunicorn command and add some ascii art.

All changes since 0.25.0.


  • Support calling functions in JavaScript modules.

  • Fix: use unicorn:db without a unicorn:model in the same element.

All changes since 0.24.0.


All changes since 0.23.0.


  • Performance enhancement that returns a 304 HTTP status code when an action happens, but the content doesn’t change.

  • Add unicorn:ignore attribute to prevent an element from being morphed (useful when using Unicorn with libraries like Select2 that change the DOM).

  • Add support for passing arguments to

  • Bug fix when attempting to cache component views that utilize the db_model decorator.

All changes since 0.22.0.


  • Use Django cache for storing component state when available

  • Add support for Django 2.2.x

All changes since 0.21.2.


  • Add backported dataclasses for Python 3.6. (@frbor)

All changes since 0.21.0.


All changes since 0.20.0.


All changes since 0.19.0.


  • Re-implemented how action method parsing is done to remove all edge cases when passing arguments to component view methods. (@frbor).

  • Add support for passing kwargs to component view methods.

All changes since 0.18.1.


  • Fix regression where component kwargs were getting lost (#140, #141)

  • Fix startunicorn management command (#142)

All changes since 0.18.0.


  • Only send updated data back in the response to reduce network latency.

  • Experimental support for queuing up requests to alleviate race conditions when functions take a long time to process.

  • Bug fix: prevent race condition where an instantiated component class would be inadvertently re-used for component views that are slow to render

  • Bug fix: use the correct component name to call a component method from “outside” the component.

  • Deprecated: DJANGO_UNICORN setting has been renamed to UNICORN.

All changes since 0.17.2.


  • Don’t send the parent context in the response for child components that specify a partial update.

  • Add support for element models to specify a partial update.

  • Add support for polls to specify a partial update.

  • Handle date, time, timespan when passed as arguments from JavaScript.

  • Render child component template’s JavaScript initialization with the parent’s as opposed to inserting a new script tag after the child component is rendered.

  • Bug fix: prevent an error when rendering a Django model with a date-related field, but a string value.

All changes since 0.17.1.


  • Remove stray print statement.

  • Fix bug where child components would sometimes lose their action events.

All changes since 0.17.0.


  • Target DOM changes from an action to only a portion of the DOM with partial updates.

All changes since 0.16.1.


  • Remove debounce from action methods to reduce any perceived lag.

All changes since 0.16.0.


  • Dirty states for when there is a change that hasn’t been synced yet.

  • Add support for setting multiple classes for loading states.

  • Attempt to handle when the component gets out of sync with an invalid checksum error.

  • Performance tweaks when there isn’t a change to a model or dbModel with lazy or defer modifiers.

All changes since 0.15.1.


  • Fix bug where a component name has a dash in its name

All changes since 0.15.1.


  • Add support for child components

  • Add discard action modifier

  • Add support for referring to components in a folder structure

  • Remove restriction that component templates must start with a div

  • Remove restriction that component root can’t also have unicorn:model or unicorn:action

All changes since 0.15.0.


  • Prevent the currently focused model element from updating after the AJAX request finishes (#100).

All changes since 0.14.0.


All changes since 0.13.0.


All changes since 0.12.0.


  • Redirect from action method in component

All changes since 0.11.2.


  • Fix encoding issue with default component template on Windows (#91)

  • Fix circular import when creating the component (#92)

All changes since 0.11.0.


  • $toggle special method.

  • Support nested properties when using the set shortcut.

  • Fix action string arguments that would get spaces removed inadvertently.

Breaking changes

  • All existing special methods now start with a $ to signify they are magical. Therefore, refresh is now $refresh, reset is now $reset, and validate is now $validate.

All changes since 0.10.1.


  • Use LRU cache for constructed components to prevent ever-expanding memory.

  • Loosen beautifulsoup4 version requirement.

  • Fix bug to handle floats so that they don’t lose precision when serialized to JSON.

  • Fix bug to handle related models (ForeignKeys, OneToOne, etc) fields in Django models.

All changes since 0.10.0.


All changes since 0.9.4.


  • Fix: Prevent Django CharField form field from stripping whitespaces when used for validation.

  • Fix: Handle edge case that would generate a null exception.

  • Fix: Only change loading state when an action method gets called, not on every event fire.

All changes since 0.9.1.


  • Handle child elements triggering an event which should be handled by a parent unicorn element.

All changes since 0.9.1.


  • Fix: certain actions weren’t triggering model values to get set correctly

All changes since 0.9.0.


All changes since 0.8.0.


  • Add much more elaborate support for dealing with Django models.

All changes since 0.7.1.


  • Fix bug where multiple actions would trigger multiple payloads.

  • Handle lazy models that are children of an action model better.

All changes since 0.7.0.


Breaking changes

  • Remove unused unicorn_styles template tag

  • Use dash for poll timing instead of dot

All changes since 0.6.5.


  • Attempt to get the CSRF token from the cookie first before looking at the CSRF token.

All changes since 0.6.4.


  • Fix bug where lazy models weren’t sending values before an action was called

  • Add is_valid method to component to more easily check if a component has validation errors.

  • Better error message if the CSRF token is not available.

All changes since 0.6.3.


  • Fix bug where model elements weren’t getting updated values when an action was being called during the same component update.

  • Fix bug where some action event listeners were duplicated.

All changes since 0.6.2.


  • More robust fix for de-duping multiple actions.

  • Fix bug where conditionally added actions didn’t get an event listener.

All changes since 0.6.1.


  • Fix model sync getting lost when there is an action (issue 39).

  • Small fix for validations.

All changes since 0.6.0.


All changes since 0.5.0.


  • Call component method from JavaScript.

  • Support classes, dictionaries, Django Models, (read-only) Django QuerySets properties on a component.

  • Debounce modifier to change how fast changes are sent to the backend from unicorn:model.

  • Lazy modifier to listen for blur instead of input on unicorn:model.

  • Better support for textarea HTML element.

All changes since 0.4.0.


  • Set shortcut for setting properties.

  • Listen for any valid event, not just click.

  • Better handling for model updates when element ids aren’t unique.

All changes since 0.3.0.


  • Add mount hook.

  • Add reset action.

  • Remove lag when typing fast in a text input and overall improved performance.

  • Better error handling for exceptional cases.

All changes since 0.2.3.


  • Fix for creating default folders when running startunicorn.

All changes since 0.2.2.


  • Set default template_name if it’s missing in component.

All changes since 0.2.1.


  • Fix startunicorn Django management command.

All changes since 0.2.0.


All changes since 0.1.1.


  • Fix package readme and repository link.

All changes since 0.1.0.


  • Initial version with basic functionality.