Installation

New Django Project with labbstart

The fastest way to get started is with labbstart, which scaffolds a new Django project with labb pre-configured.

pip install labbstart
labbstart new

This interactively prompts you for project name, Django version, package manager, and starter kit. You can also pass flags directly:

labbstart new myproject --django-version 5 --package-manager poetry --kit welcome --app-name starter

Once created, start two terminals:

# Terminal 1 — CSS watcher
cd your-project-name && labb dev

# Terminal 2 — Django server
cd your-project-name && python manage.py runserver

Open http://localhost:8000 and you're ready to build.

Existing Project

Prerequisites

Python 3.8+
Django 4.2+

Step 1: Install labb

pip install labbui

Or with Poetry:

poetry add labbui

Step 2: Add to Django Settings

Add labb to your INSTALLED_APPS:

settings.py

INSTALLED_APPS = [
    # ... other apps
    'django_cotton',
    'labb',
]

This automatically configures the required template loader and templatetags.

Custom configuration

If your project uses non-default loaders or you don't want Cotton to manage your settings, use django_cotton.apps.SimpleAppConfig instead:

settings.py

INSTALLED_APPS = [
    # ... other apps
    'django_cotton.apps.SimpleAppConfig',
    'labb',
]

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],
        'APP_DIRS': False,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
            'loaders': [
                (
                    'django.template.loaders.cached.Loader',
                    [
                        'django_cotton.cotton_loader.Loader',
                        'django.template.loaders.filesystem.Loader',
                        'django.template.loaders.app_directories.Loader',
                    ],
                )
            ],
            'builtins': [
                'django_cotton.templatetags.cotton',
            ],
        },
    },
]

Step 3: Initialize and Set Up

labb init --defaults
labb setup

labb init creates the project configuration and structure. labb setup installs the required Node.js dependencies.

Step 4: Add Dependencies to Your Template

Add <c-lb.m.dependencies /> to your base template's <head> section:

templates/base.html

{% load lb_tags %}

<!DOCTYPE html>
<html lang="en" {% labb_theme %}>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My labb App</title>
    <c-lb.m.dependencies setThemeEndpoint="{% url 'set_theme' %}" />
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>

Without <c-lb.m.dependencies />, components will not have the correct styling and interactive features may not work.

Step 5: Icons (optional)

To use icons in your components, install labbicons:

pip install labbicons
# or together with labb
pip install labbui[icons]

Add labbicons to INSTALLED_APPS:

settings.py

INSTALLED_APPS = [
    # ... other apps
    'django_cotton',
    'labb',
    'labbicons',
]

Then use icons in any component that accepts an icon prop, or directly:

<c-lb.button icon="rmx.heart">Like</c-lb.button>
<c-lbi.rmx.heart w="24" h="24" />

See the Icons guide for the full reference.

Step 6: Start Developing

Start two terminals:

# Terminal 1 — CSS watcher
labb dev

# Terminal 2 — Django server
python manage.py runserver

Basic Usage

Use labb components in your templates with HTML-like syntax:

templates/example.html

<c-lb.button variant="primary">Click me</c-lb.button>

<c-lb.card>
    <c-lb.card.body>
        <c-lb.card.title>Card Title</c-lb.card.title>
        <p>Card content goes here</p>
    </c-lb.card.body>
</c-lb.card>

<c-lb.alert variant="success">Success message!</c-lb.alert>

Browse component documentation for all available components.

Reactive Components

Add .x to any component name to get a reactive twin. Props can be changed at runtime using Alpine.js:

templates/example.html

<div x-data="{ btn: { variant: 'primary' } }">
    <c-lb.button.x x-model="btn" variant="primary">
        <span x-text="btn.variant"></span> button
    </c-lb.button.x>

    <c-lb.button variant="ghost" @click="btn.variant = 'success'">Change</c-lb.button>
</div>

See the Reactivity guide for the full picture.

Next Steps

Theming — Customize colors and themes
Building CSS — CSS build process and production builds
Reactivity — Add Alpine.js-powered interactivity to components with .x variants
CLI Reference — Component inspection, icon search, and more
Icons — Install labbicons for 2,800+ Remix icons