cotton
for
Docs syntax
<c> tags: Snippets will be shown in Cotton's HTML-like tag syntax.
Native: Snippets will be shown in native Django template syntax.
More info
Getting Started
Tutorials
Usage Patterns

Goodbye {% extends %} {% block %} {% include %} {% custom_tag %}
Hello <c-cotton>

Bringing component-based design to django templates

Native DTL: Verbose & Limited

{# ❌ include: HTML is escaped,
   <b>Bold</b> shows as literal text #}
{% include "card.html" with
    content="<b>Bold</b>" %}

{# ❌ extends: only one per template #}
{% extends "card.html" %}
{% block content %}Card 1{% endblock %}

{# ❌ templatetags: needs a .py file #}
{% load card %}
{% card %}

Cotton: Composable & Re-usable

{# ✅ pass rich HTML content #}
<c-card title="First Card">
    <b>Bold</b>, <a href="#">links</a>, anything
</c-card>

{# ✅ reuse unlimited times #}
<c-card title="Second Card">
    <c-slot name="footer">Named slots</c-slot>
</c-card>

{# ✅ just an HTML file, no Python #}
<c-alert type="warning">No Python needed</c-alert>
{# ✅ pass rich HTML content #}
{% cotton card title="First Card" %}
    <b>Bold</b>, <a href="#">links</a>, anything
{% endcotton %}

{# ✅ reuse unlimited times #}
{% cotton card title="Second Card" %}
    {% cotton:slot footer %}Named slots{% endcotton:slot %}
{% endcotton %}

{# ✅ just an HTML file, no Python #}
{% cotton alert type="warning" %}No Python needed{% endcotton %}

New to components? Start with Thinking in Components.

Why cotton?

Rapid UI composition
Create reusable UI components from a single HTML file, no Python required. Composing from small, modular pieces streamlines your workflow and boosts productivity.
Harmonious with Tailwind CSS
Tailwind's utility-first approach compliments component based design - isolating style in re-usable components, enhancing maintainability.
{%
Interoperable with Django Templates
Cotton enhances Django templates without replacing them, allowing progressive enhancement while maintaining full use of existing template features.
Enhanced Productivity
Cotton's HTML tag-like syntax allows code editors to recognize its components as HTML elements, enabling features like syntax highlighting and automatic tag completion.
Minimal Overhead
Cotton compiles to native Django template tags with built-in compilation caching. Template files are only re-processed when modified, and when used with Django's cached.Loader (applied automatically by default), fully parsed templates are cached for the lifetime of the process.
next Thinking in Components