https://github.com/fabiocaccamo/django-colorfield
:art: color field for django models with a nice color-picker in the admin.
https://github.com/fabiocaccamo/django-colorfield
admin color colorfield colorpicker django field interface jscolor model models picker python
Last synced: 7 months ago
JSON representation
:art: color field for django models with a nice color-picker in the admin.
- Host: GitHub
- URL: https://github.com/fabiocaccamo/django-colorfield
- Owner: fabiocaccamo
- License: mit
- Created: 2010-05-03T20:19:39.000Z (over 15 years ago)
- Default Branch: main
- Last Pushed: 2025-04-07T17:03:07.000Z (7 months ago)
- Last Synced: 2025-04-11T08:06:38.038Z (7 months ago)
- Topics: admin, color, colorfield, colorpicker, django, field, interface, jscolor, model, models, picker, python
- Language: Python
- Homepage:
- Size: 360 KB
- Stars: 647
- Watchers: 6
- Forks: 96
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-django-admin - django-colorfield - Color field for django models with a nice color-picker in the admin (Packages to install at your project / Widgets / Fields)
- awesome-django - django-colorfield - Color field for django models with a nice color-picker widget. (Third-Party Packages / Model Fields)
README
[](https://www.python.org/)
[](https://www.djangoproject.com/)
[](https://pypi.org/project/django-colorfield/)
[](https://pepy.tech/project/django-colorfield)
[](https://github.com/fabiocaccamo/django-colorfield/stargazers)
[](https://github.com/fabiocaccamo/django-colorfield/blob/main/LICENSE.txt)
[](https://results.pre-commit.ci/latest/github/fabiocaccamo/django-colorfield/main)
[](https://github.com/fabiocaccamo/django-colorfield)
[](https://codecov.io/gh/fabiocaccamo/django-colorfield)
[](https://www.codacy.com/app/fabiocaccamo/django-colorfield)
[](https://codeclimate.com/github/fabiocaccamo/django-colorfield/)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
# django-colorfield
simple color field for your models with a nice color-picker in the admin-interface.
---
## Installation
- Run `pip install django-colorfield`
- Add `colorfield` to `settings.INSTALLED_APPS`
- Run `python manage.py collectstatic`
- Restart your application server
---
## Usage
### Settings
This package doesn't need any setting.
### Models
Just add color field(s) to your models like this:
```python
from colorfield.fields import ColorField
from django.db import models
class MyModel(models.Model):
color = ColorField(default='#FF0000')
```
### Field Options
These are the supported custom options: [`format`](#format), [`image_field`](#image_field), [`samples`](#samples)
#### format
The following formats are supported: `hex` *(default)*, `hexa`, `rgb`, `rgba`.
```python
from colorfield.fields import ColorField
from django.db import models
class MyModel(models.Model):
color = ColorField(format="hexa")
```
#### image_field
It is possible to auto-populate the field value getting the color from an image using the `image_field` option.
The color will be calculated from the **top-left pixel** color of the image each time the model instance is saved.
```python
from colorfield.fields import ColorField
from django.db import models
class MyModel(models.Model):
image = models.ImageField(upload_to="images")
color = ColorField(image_field="image")
```
#### samples
It is possible to provide a palette of colors to choose from to the widget using the `samples` option.
This option **is not restrictive** (on the contrary of `choices` option), it is also possible to choose another color from the spectrum.
```python
from colorfield.fields import ColorField
from django.db import models
class MyModel(models.Model):
COLOR_PALETTE = [
("#FFFFFF", "white", ),
("#000000", "black", ),
]
# not restrictive, allows the selection of another color from the spectrum.
color = ColorField(samples=COLOR_PALETTE)
# restrictive, it is mandatory to choose a color from the palette
color = ColorField(choices=COLOR_PALETTE)
```
### Forms
#### Model forms
The `colorfield.fields.ColorField` can be used in Django model forms (`django.forms.ModelForm`) to provide a color picker widget.
When used in a model form, the field automatically validates the color format based on the specified `format` (e.g., `hex`, `rgb`, `rgba`).
```python
from django import forms
class MyModelForm(forms.ModelForm):
class Meta:
model = MyModel
fields = ["color"]
```
#### Plain forms
The `colorfield.forms.ColorField` can be used in plain Django forms (`django.forms.Form`) to provide a color-picker widget.
This is useful when you need a color input outside of a model context.
```python
from django import forms
from colorfield.forms import ColorField
class MyForm(forms.Form):
color = ColorField(initial="#FF0000", format="hex")
```
### Admin
The admin will kindly provide a simple [color picker](http://jscolor.com/) for all color fields. :)
---
## Testing
```bash
# clone repository
git clone https://github.com/fabiocaccamo/django-colorfield.git && cd django-colorfield
# create virtualenv and activate it
python -m venv venv && . venv/bin/activate
# upgrade pip
python -m pip install --upgrade pip
# install requirements
pip install -r requirements.txt -r requirements-test.txt
# install pre-commit to run formatters and linters
pre-commit install --install-hooks
# run tests
tox
# or
python runtests.py
# or
python -m django test --settings "tests.settings"
```
---
## Credits
Originally developed by [Jared Forsyth](https://github.com/jaredly)
---
## License
Released under [MIT License](LICENSE.txt).
---
## Supporting
- :star: Star this project on [GitHub](https://github.com/fabiocaccamo/django-colorfield)
- :octocat: Follow me on [GitHub](https://github.com/fabiocaccamo)
- :blue_heart: Follow me on [Twitter](https://twitter.com/fabiocaccamo)
- :moneybag: Sponsor me on [Github](https://github.com/sponsors/fabiocaccamo)
## See also
- [`django-admin-interface`](https://github.com/fabiocaccamo/django-admin-interface) - the default admin interface made customizable by the admin itself. popup windows replaced by modals. 🧙 ⚡
- [`django-cache-cleaner`](https://github.com/fabiocaccamo/django-cache-cleaner) - clear the entire cache or individual caches easily using the admin panel or management command. 🧹✨
- [`django-extra-settings`](https://github.com/fabiocaccamo/django-extra-settings) - config and manage typed extra settings using just the django admin. ⚙️
- [`django-maintenance-mode`](https://github.com/fabiocaccamo/django-maintenance-mode) - shows a 503 error page when maintenance-mode is on. 🚧 🛠️
- [`django-redirects`](https://github.com/fabiocaccamo/django-redirects) - redirects with full control. ↪️
- [`django-treenode`](https://github.com/fabiocaccamo/django-treenode) - probably the best abstract model / admin for your tree based stuff. 🌳
- [`python-benedict`](https://github.com/fabiocaccamo/python-benedict) - dict subclass with keylist/keypath support, I/O shortcuts (base64, csv, json, pickle, plist, query-string, toml, xml, yaml) and many utilities. 📘
- [`python-codicefiscale`](https://github.com/fabiocaccamo/python-codicefiscale) - encode/decode Italian fiscal codes - codifica/decodifica del Codice Fiscale. 🇮🇹 💳
- [`python-fontbro`](https://github.com/fabiocaccamo/python-fontbro) - friendly font operations. 🧢
- [`python-fsutil`](https://github.com/fabiocaccamo/python-fsutil) - file-system utilities for lazy devs. 🧟♂️