Quick Start

Get django-palette running in 5 minutes!

Installation (1 minute)

Install the package:

pip install dj-palette

Add to settings.py:

INSTALLED_APPS = [
    'dj_palette',
    'dj_palette.palette_admin', # optional, only if you want the best looking admin UI
    'django.contrib.admin',
    # ... rest of your apps
]

Run migrations:

python manage.py migrate

Collect static files:

python manage.py collectstatic

Start the server:

python manage.py runserver

Visit http://localhost:8000/admin/ and you’ll see the beautiful django-palette admin interface!

Creating a Component (2 minutes)

Create a file templates/components/stat_card.html:

{% load palette %}

{% palette_component "stat_card" %}
  <div class="card border-0 shadow-sm">
    <div class="card-body text-center">
      {% palette_block "stat_content" %}
        <h2 class="display-4 text-primary">{{ number }}</h2>
        <p class="text-muted">{{ label }}</p>
      {% endpalette_block %}
    </div>
  </div>
{% endpalette_component %}

Using the Component (2 minutes)

In your template (e.g., templates/admin/index.html):

{% load palette %}

<div class="row">
  <div class="col-md-4">
    {% palette_ui "stat_card" with number="1,234" label="Total Users" %} {% endpalette_ui %}
  </div>

  <div class="col-md-4">
    {% palette_ui "stat_card" with number="89" label="Active Today" %}
      {% palette_override "stat_content" %}
        <h2 class="display-4 text-success">{{ number }}</h2>
        <p class="text-muted">{{ label }}</p>
        <small>Updated just now</small>
      {% endpalette_override %}
    {% endpalette_ui %}
  </div>
</div>

That’s it! You now have:

✅ A beautiful admin interface ✅ A reusable component ✅ The ability to customize components with overrides

What’s Next?

Learn More

Features - Explore all features
Template Tags - Learn all template tags
Components - Build more complex components
Examples - See more examples

Customize Further

Override admin templates in your project’s templates/admin/ directory
Create more components in templates/components/ or <your_app>/templates/<your_app>/components/ (always use named subfolders when going with in-app templates approach)
Use the filters: admin_fields and admin_field

Need Help?

Check the Features page for more information
Read the full Template Tags documentation
See Examples for more code examples
Open an issue on GitHub

Key Concepts

Components: Reusable UI elements defined with palette_component

Blocks: Named areas within components that can be overridden with palette_override

Rendering: Use palette_ui to render a component with context variables

Customization: Override blocks without redefining entire components

Example: Creating a Dashboard

Create templates/admin/index.html:

{% extends "admin/base_site.html" %}
{% load palette %}

{% block content %}
  <div class="container-fluid">
    <h1>Dashboard</h1>

    <div class="row mt-4">
      <div class="col-md-4">
        {% palette_ui "stat_card" with number="1,234" label="Total Users" %}{% endpalette_ui %}
      </div>
      <div class="col-md-4">
        {% palette_ui "stat_card" with number="456" label="Active Sessions" %}{% endpalette_ui %}
      </div>
      <div class="col-md-4">
        {% palette_ui "stat_card" with number="789" label="Total Orders" %}{% endpalette_ui %}
      </div>
    </div>
  </div>
{% endblock %}

This creates a beautiful dashboard with three stat cards!

Ready?

Start building! Check out Examples for more ideas.