{"id":5906,"library":"django-cotton","title":"Django Cotton","description":"Django Cotton enhances Django's existing template system to enable modern UI composition through a component-based design. It introduces an HTML-like syntax for creating reusable UI components, aiming to overcome limitations in native Django templates regarding modularity and reusability. Version 2.6.2 is currently active, with a focus on seamless integration, minimal overhead through dynamic caching, and improved developer experience.","status":"active","version":"2.6.2","language":"en","source_language":"en","source_url":"https://github.com/wrabit/django-cotton","tags":["Django","UI","Templating","Components","Frontend","HTML-like"],"install":[{"cmd":"pip install django-cotton","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Django Cotton is a Django-specific library and requires a compatible Django version.","package":"Django","optional":false},{"reason":"Requires Python 3.8 or newer, but less than 4.","package":"Python","optional":false}],"imports":[{"note":"Add 'django_cotton' to your Django project's INSTALLED_APPS in settings.py. This usually handles automatic loader and templatetag configuration.","symbol":"django_cotton","correct":"INSTALLED_APPS = ['django_cotton', ...]"}],"quickstart":{"code":"<!-- settings.py -->\nINSTALLED_APPS = [\n    # ... other apps\n    'django_cotton',\n]\n\n# Optional: Manual TEMPLATES configuration if you have custom loaders\n# TEMPLATES = [\n#     {\n#         'BACKEND': 'django.template.backends.django.DjangoTemplates',\n#         'DIRS': [],\n#         'APP_DIRS': False, # Set to False if DIRS is used for project-level templates\n#         'OPTIONS': {\n#             'loaders': [\n#                 ('django.template.loaders.cached.Loader', [\n#                     'django_cotton.template.loaders.CottonLoader',\n#                     'django.template.loaders.filesystem.Loader',\n#                     'django.template.loaders.app_directories.Loader',\n#                 ]),\n#             ],\n#             'builtins': [\n#                 'django_cotton.templatetags.cotton',\n#             ],\n#         },\n#     },\n# ]\n\n# --- In your templates directory (e.g., myproject/templates/cotton/button.html) ---\n<button class=\"p-2 rounded-md bg-blue-500 text-white hover:bg-blue-600\">\n    {{ slot }}\n</button>\n\n# --- In a main Django template (e.g., myproject/templates/index.html) ---\n<h1 class=\"text-2xl font-bold\">Welcome!</h1>\n<c-button>Click Me</c-button>\n<c-button class=\"bg-green-500 hover:bg-green-600\">Submit</c-button>","lang":"html+django","description":"1. Add `django_cotton` to your `INSTALLED_APPS` in `settings.py`. This typically configures the necessary template loaders automatically. 2. Create a `cotton` directory within your Django app's `templates` folder or a project-level `templates` folder. 3. Define a component, for example, `button.html`, inside the `cotton` directory. The `{{ slot }}` variable renders any content passed between the component's opening and closing tags. 4. Use the component in your main Django templates using the HTML-like `c-` prefixed tag and kebab-case naming."},"warnings":[{"fix":"Review any custom code that might have directly referenced internal Django Cotton template tags. Migrate to documented public APIs or the HTML-like component syntax.","message":"Internal template tag names changed in version 2.4.0. While these were not officially documented for external use, direct reliance on previous internal tag names would break upon upgrade.","severity":"breaking","affected_versions":">=2.4.0"},{"fix":"Explicitly add `django_cotton.template.loaders.CottonLoader` to your `TEMPLATES` `OPTIONS.loaders` list, ideally wrapped by `django.template.loaders.cached.Loader` for optimal performance.","message":"If your project uses a custom `TEMPLATES` loader configuration, automatic setup by adding 'django_cotton' to `INSTALLED_APPS` might be insufficient. You may need to manually configure the `CottonLoader`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be mindful of the casing convention. You can configure `COTTON_SNAKE_CASED_NAMES = False` in `settings.py` to allow kebab-case filenames for components if preferred.","message":"Components are referenced in templates using kebab-case (e.g., `<c-my-component />`), but component filenames typically use snake_case by default (e.g., `my_component.html`). This naming convention difference can sometimes be a source of confusion.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `django_cotton` is correctly listed in `INSTALLED_APPS` and that the template loader configuration is valid. If using manual loader setup, double-check its correctness. If issues persist, consider using the native `{% cotton %}` tag as an alternative.","message":"In some setups, particularly older ones or with specific environment configurations, the HTML-like component syntax (`<c-component />`) might render as raw HTML in the browser rather than being processed by Django Cotton. The native `{% cotton %}` tag typically still works in such cases.","severity":"gotcha","affected_versions":"Potentially all, more common in older versions or misconfigurations"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}