adminita 0.1.8

A modern admin interface for Django using Tailwind CSS v4

readme for 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
• ⚡ 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

![Dark Mode Dashboard - IMAGE COMING SOON - once I fix it!]

🚀 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 -e .

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. Run your server:

python manage.py runserver

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

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

🎨 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 they have custom 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):

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
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/
│   │   ├── css/
│   │   │   └── adminita-tailwind.css    # Generated CSS (don't edit)
│   │   ├── js/
│   │   │   └── adminita-tailwind.js      # JavaScript for dark mode & mobile menu
│   │   └── src/
│   │       └── input.css     # Source CSS with Tailwind v4 syntax
│   ├── templates/
│   │   └── admin/            # Template overrides
│   │       ├── base.html
│   │       ├── base_site.html
│   │       ├── index.html
│   │       ├── login.html
│   │       ├── change_list.html
│   │       └── change_form.html
│   ├── __init__.py
│   └── apps.py
├── config/                    # Django project settings
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── package.json              # Node.js dependencies for Tailwind
├── pyproject.toml            # Python package configuration
└── README.md

🐛 Known Issues

Issue: Search and filters break after zero-result state

Symptoms

• Search returns correct results
• Filters work initially
• After any action that returns zero results, filters stop working
• JavaScript error: undefined is not iterable in actions.js

Root cause

Django's admin/js/actions.js expects specific DOM elements that may not exist when the result set is empty, causing a JavaScript crash that breaks subsequent page functionality.

Workaround

Disable admin actions or add error handling for the zero-result state.

Known Limitations

These changes make Adminita usable on mobile, not optimized for mobile:

• 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.

How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Test thoroughly
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Priority Issues

We especially need help with:

• 🐛 Dark Mode Bug - The toggle isn't working (UPDATE: This now works as of December 21 2025)
• 📱 Mobile Responsiveness - Testing on various devices
• ♿ Accessibility - ARIA labels, keyboard navigation, screen reader support
• 🎨 Additional Themes - Creating alternative color schemes
• 📝 Documentation - Improving guides and examples

Development Guidelines

• Follow Django's template style guidelines
• Use Tailwind CSS utility classes (avoid custom CSS when possible)
• Test on multiple browsers (Chrome, Firefox, Safari, Edge)
• Ensure dark mode compatibility for all new features
• Update documentation for any new features

📦 Requirements

• Python 3.10+
• Django 4.2+
• Node.js (for building CSS during development)
• npm (for managing Tailwind CSS)

🧪 Testing

# Run Django tests
python manage.py test

# Test in multiple browsers
# Test dark mode toggle
# Test responsive design on mobile devices

📄 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

• Fix dark mode toggle functionality
• Add more customization options
• Create additional color themes
• Improve accessibility (ARIA labels, keyboard navigation)
• Add comprehensive test suite
• Create video tutorials
• Publish to PyPI
• 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 ❤️