https://github.com/djangify/adminita
Django Tailwind Admin UI
https://github.com/djangify/adminita
django django-admin django-admin-theme django-admin-themes
Last synced: 18 days ago
JSON representation
Django Tailwind Admin UI
- Host: GitHub
- URL: https://github.com/djangify/adminita
- Owner: djangify
- License: mit
- Created: 2025-12-06T21:35:29.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-09T12:02:42.000Z (5 months ago)
- Last Synced: 2026-07-03T03:35:21.697Z (18 days ago)
- Topics: django, django-admin, django-admin-theme, django-admin-themes
- Language: HTML
- Homepage: https://adminita.todiane.com
- Size: 884 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 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
## 🚀 Quick Start
### Installation
1. **Install via pip** (recommended for production):
```bash
pip install adminita
```
2. **Or install from source** (for development):
```bash
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`):
```python
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**:
```python
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`:
```python
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**:
```bash
python manage.py collectstatic --noinput
```
5. **Run your server**:
```bash
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`:
```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**:
```bash
cd path/to/adminita
npm install # If you haven't already
npm run build
```
3. **Collect static files** in your project:
```bash
python manage.py collectstatic --noinput
```
### Available Color Variables
```css
--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:
```python
from adminita.utils import AlwaysVisibleAdmin
@admin.register(MyModel)
class MyModelAdmin(AlwaysVisibleAdmin):
pass
```
### SingletonAdmin
For models that should only have one instance (like Site Settings):
```python
from adminita.utils import SingletonAdmin
@admin.register(SiteConfiguration)
class SiteConfigurationAdmin(SingletonAdmin):
list_display = ['site_name']
```
## 🛠️ Development
### Setting Up Development Environment
1. **Clone the repository**:
```bash
git clone https://github.com/djangify/adminita.git
cd adminita
```
2. **Create a virtual environment**:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. **Install dependencies**:
```bash
pip install -r requirements.txt
npm install
```
4. **Build CSS**:
```bash
npm run build # One-time build
npm run watch # Auto-rebuild on changes
```
5. **Run the demo project**:
```bash
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:
```django
{% 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
```bash
# 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](LICENSE) file for details.
## 👏 Acknowledgments
- Built with [Django](https://www.djangoproject.com/)
- Styled with [Tailwind CSS v4](https://tailwindcss.com/)
- 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](https://adminita.todiane.com/infopages/docs)
- 🐛 [Open an issue](https://github.com/djangify/adminita/issues/new)
- 💡 [Start a discussion](https://github.com/djangify/adminita/discussions)
## 🗺️ 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 ❤️
Maintained by [Diane Corriette](https://github.com/todiane)