adminita

Adminita

A modern, beautiful Django admin theme built with Tailwind CSS v4. Transform your Django admin interface into a sleek, responsive dashboard with dark mode support.

✨ Features

• 🎨 Modern UI - Clean, professional interface built with Tailwind CSS v4
• 🌓 Dark Mode - System preference detection with manual toggle
• 📱 Responsive Design - Works seamlessly on desktop. Responsive navigation and touch-friendly controls for phones and tablets
• 🎯 Easy Integration - Drop-in replacement for Django's default admin
• 💾 Form Autosave - Unsaved edits survive a refresh or closed tab, with a Restore/Discard prompt that never overwrites newer changes
• ⚡ Fast - Optimized CSS with no unnecessary bloat
• 🔧 Customizable - Easy to customize colors and styling
• 🆓 Open Source - MIT licensed, free to use and modify

📸 Screenshots

Light Mode

Dark Mode

🚀 Quick Start

Installation

1. Install via pip (recommended for production):

pip install adminita

2. Or install from source (for development):

git clone https://github.com/djangify/adminita.git
cd adminita
pip install -r requirements.txt   # demo project dependencies
pip install -e .
python manage.py migrate
python manage.py createsuperuser

The demo project reads optional settings from a .env file (see .env.example); it runs without one for local use.

Configuration

1. Add to INSTALLED_APPS in your Django settings (must be before django.contrib.admin):

INSTALLED_APPS = [
    "adminita",  # Must be FIRST!
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # ... your other apps
]

2. Configure static files:

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

3. Add customization to project urls.py file: Adminita uses Django's built-in admin site customization. Add these lines to your urls.py:

from django.contrib import admin

admin.site.site_header = "Your Site Name"
admin.site.site_title = "Your Site Title" 
admin.site.index_title = "Welcome to Your Site"

4. Collect static files:

python manage.py collectstatic --noinput

5. Create the database tables and an admin user (skip if your project already has them):

python manage.py migrate
python manage.py createsuperuser

6. Run your server:

python manage.py runserver

7. Visit the admin at http://localhost:8000/admin/

That's it! Your Django admin should now have the Adminita theme applied.

🆕 What's New in 0.2.0

• Security fix for the "add related object" popup (XSS via object names)
• Related-field popups fixed: many-to-many fields keep existing selections, filter_horizontal / filter_vertical receive new items, and raw ID lookups work
• Change list actions fixed: selection counter, "Select all N across pages" and actions after searching or filtering
• Safer form autosave with a Restore / Discard prompt
• Dark mode now follows your system setting until you use the toggle
• Logout and password change pages now use Adminita's design
• Tested on Django 4.2 to 6.0

Upgrading from 0.1.x

1. Upgrade the package and re-collect static files:

pip install --upgrade adminita
python manage.py collectstatic --noinput

2. If your settings include "adminita.context_processors.admin_app_list" in TEMPLATES, remove it. It's no longer needed and now only raises a deprecation warning.

3. AlwaysVisibleAdmin and SingletonAdmin now follow Django's model permissions. Staff users who aren't superusers need view (and change) permission on those models to see them. Superusers are not affected.

🎨 Customization

Changing Colors

Adminita uses Tailwind CSS v4's new @theme syntax. To customize colors:

1. Edit the source CSS at adminita/static/src/input.css:

@theme {
  /* Change primary colors to match your brand */
  --color-primary-500: #10b981; /* Your brand color */
  --color-primary-600: #059669; /* Darker shade */
  --color-primary-700: #047857; /* Even darker */
}

2. Rebuild the CSS:

cd path/to/adminita
npm install  # If you haven't already
npm run build

3. Collect static files in your project:

python manage.py collectstatic --noinput

Available Color Variables

--color-primary-50 through --color-primary-950
--color-gray-50 through --color-gray-900
--color-gray-750 (custom for dark mode)

🔧 Utility Classes

Adminita provides utility classes to help with common admin patterns.

AlwaysVisibleAdmin

Ensures models always appear in the admin index, even if the changelist redirects or add is disabled. Viewing and editing still follow Django's normal model permissions:

from adminita.utils import AlwaysVisibleAdmin

@admin.register(MyModel)
class MyModelAdmin(AlwaysVisibleAdmin):
    pass

SingletonAdmin

For models that should only have one instance (like Site Settings). The changelist goes straight to the existing instance, adding is blocked once one exists (or if the user lacks add permission), and deleting is disabled:

from adminita.utils import SingletonAdmin

@admin.register(SiteConfiguration)
class SiteConfigurationAdmin(SingletonAdmin):
    list_display = ['site_name']

🛠️ Development

Setting Up Development Environment

1. Clone the repository:

git clone https://github.com/djangify/adminita.git
cd adminita

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt
pip install -e ".[dev]"   # Adminita itself plus pytest, ruff and black
npm install

4. Build CSS:

npm run build    # One-time build
npm run watch    # Auto-rebuild on changes

5. Run the demo project:

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Project Structure

adminita/
├── adminita/                  # The Django app package
│   ├── static/
│   │   ├── adminita/
│   │   │   ├── adminita-tailwind.css    # Generated CSS (don't edit)
│   │   │   ├── action-fix.css           # Styles for Django's own widget markup
│   │   │   ├── adminita-tailwind.js     # JavaScript for dark mode & mobile menu
│   │   │   └── adminita-autosave.js     # Keeps unsaved form edits (restore/discard banner)
│   │   └── src/
│   │       └── input.css     # Source CSS with Tailwind v4 syntax
│   ├── templates/
│   │   ├── admin/            # Template overrides
│   │   │   ├── base.html
│   │   │   ├── index.html
│   │   │   ├── login.html
│   │   │   ├── change_list.html
│   │   │   └── change_form.html
│   │   └── registration/     # Points Django's logout/password pages at Adminita's versions
│   ├── templatetags/         # adminita_tags (readonly field rendering)
│   ├── utils.py              # AlwaysVisibleAdmin, SingletonAdmin
│   ├── __init__.py
│   └── apps.py
├── config/                    # Django project settings
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── tests/                     # pytest suite
├── manage.py
├── package.json              # Node.js dependencies for Tailwind
├── pyproject.toml            # Python package configuration
└── README.md

Known Limitations

Adminita is usable on mobile, but not yet optimized for it:

• Complex tables - Very wide tables still require horizontal scrolling
• Inline formsets - Tabular inlines are cramped; consider using stacked inlines for mobile-heavy use cases
• Rich text editors - TinyMCE and similar may have their own mobile issues
• Date/time pickers - Django's default widgets are desktop-focused

Future Improvements (Community PRs Welcome)

• Card-based table view option for mobile (instead of horizontal scroll)
• Bottom navigation bar for common actions
• Pull-to-refresh on list pages
• Improved inline formset mobile layout
• Native date/time inputs on mobile ()

📚 Documentation

Tailwind CSS v4 Notes

Adminita uses Tailwind CSS v4, which has a different syntax than v3:

• Uses @import "tailwindcss" instead of @tailwind directives
• Theme customization uses @theme {} blocks in CSS
• More streamlined, CSS-first approach

Template Inheritance

When extending Adminita templates in your own project:

{% extends "admin/base.html" %}

Not adminita/admin/base.html - Django finds templates automatically because adminita is in INSTALLED_APPS.

🤝 Contributing

We welcome contributions! Adminita is an open-source project and we'd love your help making it better. See CONTRIBUTING.md for the full guide (setup, coding standards, PR process) and our Code of Conduct.

Priority Issues

We especially need help with:

• 📱 Mobile Responsiveness - Testing on various devices
• ♿ Accessibility - ARIA labels, keyboard navigation, screen reader support
• 🎨 Additional Themes - Creating alternative color schemes
• 🧪 Test Coverage - Expanding the test suite
• 📝 Documentation - Improving guides and examples

📦 Requirements

• Python 3.10+ (3.12+ for Django 6.0)
• Django 5.2 or 6.0 (older releases are end-of-life and no longer supported)
• Node.js (for building CSS during development)
• npm (for managing Tailwind CSS)

🧪 Testing

pytest                   # Run the Python test suite
npm test                 # Run the JavaScript tests (needs `npm install` first)
ruff check .             # Lint
black --check .          # Formatting

Tests run automatically on every pull request via GitHub Actions across supported Python/Django versions. Manual checks worth doing before submitting a PR: multiple browsers (Chrome, Firefox, Safari, Edge), dark mode toggle, and responsive layout on mobile.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👏 Acknowledgments

• Built with Django
• Styled with Tailwind CSS v4
• Inspired by modern admin dashboards

🔗 Links

• GitHub: https://github.com/djangify/adminita

• Issues: https://github.com/djangify/adminita/issues

• PyPI: https://pypi.org/project/adminita/

• Website - GitHub: https://github.com/djangify/adminita_demo

• Website: https://adminita.todiane.com (demo user login available)

💬 Support

Having trouble? Here are some ways to get help:

• 📖 Check the documentation
• 🐛 Open an issue
• 💡 Start a discussion

🗺️ Roadmap

• Publish to PyPI
• Fix dark mode toggle functionality
• Django 6.0 support
• Add more customization options
• Create additional color themes
• Improve accessibility (ARIA labels, keyboard navigation)
• Expand automated test coverage
• Create video tutorials
• Add support for Django inline forms
• Create a documentation website

⭐ Star History

If you find Adminita useful, please consider giving it a star on GitHub! It helps others discover the project.

---

Made with ❤️ by a Django enthusiast

Note: This is an open-source project. I appreciate your patience and contributions!

Developer: https://www.todiane.com

Developer LinkedIn: https://linkedin.com/in/todianedev

Coffee Always Welcome: https://ko-fi.com/todianedev ❤️

Maintained by Diane Corriette