README.md
[](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)
```
### 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. 🧟♂️