# django-bootstrap-icons
[](https://github.com/christianwgd/django-bootstrap-icons/actions/workflows/django-test.yml)
[](https://github.com/astral-sh/ruff)
[](https://codecov.io/gh/christianwgd/django-bootstrap-icons)
A quick way to add [Bootstrap Icons](https://icons.getbootstrap.com) with Django
template tags.
Embed bootstrap svg icons in your django templates with the possibility for styling
and sizing.
## Installing
`django-bootstrap-icons` can be found on pypi. Run `pip install django-bootstrap-icons`
to install the package on your machine or in your virtual environment.
## Getting Started
Using django-bootstrap-icons is easy. First, add the `django_bootstrap_icons`
Django app in your settings file.
```
INSTALLED_APPS = [
'django_bootstrap_icons'
]
```
Also, load the tag library in your template file:
```
{% load bootstrap_icons %}
```
Then, add an icon with the following tag. Give the icon's name as the
first parameter, and that's all that's required:
```
{% bs_icon 'alarm' %}
```
### Icon sizes
You can size the icons by setting the size parameter:
```
{% bs_icon 'alarm' size='1.5em' %}
```
### Icon styling
Set the color of an icon by specifying the color parameter:
```
{% bs_icon 'alarm' color='red' %}
```
For further styling, you can add extra css classes:
```
{% bs_icon 'alarm' extra_classes="your-classname1 your-classname2" %}
```
#### Vertical alignment
By default, all sgv bootstrap icons are vertical aligned to the middle. Sometimes this is
not appropriate, especially when rendering beside text. To align with text *django-bootstrap-icons*
provides some css classes to set the desired vertical alignment.
Include the css file into your template
```
<link rel="stylesheet" href="{% static 'bootstrap_icons/css/bootstrap_icons.css' %}">
```
and add the class to the *extra_classes* parameter
```
{% bs_icon 'alarm' extra_classes="bi-valign-bottom" %}
```
The following classes are available:
```
.bi-valign-default /* This is a compromise also provided by bootstrap
for the icon font. The value is vertical-align: -.125em;
(see https://github.com/twbs/icons/issues/601 for details) */
.bi-valign-middle /* this is the default from bootstrap for svg */
.bi-valign-bottom
.bi-valign-text-top
.bi-valign-text-bottom
```
If you have included the django-bootstrap-icons css, the default alignment will be to
the values from ".bi-valign-default", so no need to add a class explicitly.
### Custom icons
There's a template tag for your custom icons. Store the custom icons in some
static directory. SET the BS_ICONS_CUSTOM_PATH setting to point to that static directory.
```
{% custom_icon 'your-custom-svg-name' %}
```
The custom template accepts the same parameter as the bootstrap icon template.
In fact you could download the bootstrap icons from bootstrap, store them in
your static files and use them with the custom_icon template tag. This would
avoid the use of CDN completely.
### Material Design Icons
*django-bootstrap-icons* works fine with Material Design Icons. There is a template
tag for MDI:
```
{% md_icon 'alarm' %}
```
Material Design Icons get some additional css classes *mdi* and *mdi-<icon-name>* to
style them globally.
To use Material Design Icons side-by-side with bootstrap icons *django-bootstrap-icons*
makes some adjustments in rendering the icons:
* The base size of Material Design Icons is larger than the size of bootstrap icons.
For the default size (no size attribute given), *django-bootstrap* icons are resized.
If you want to have the same size as Bootstrap Icons, set them to a size factor of 1.25.
If Bootstrap Icon is of size 2em, set Material Icon to 2.5em. (Although the base size
in mdi svgs is 24 the real size of the icon is 20 because of some empty space, that
surrounds the icons).
* Because of that empty white space of the MDI (sort of some internal "padding" in svg)
you need to include the django-bootstrap-icons css file to make some adjustments to
the alignment.
```
<link rel="stylesheet" href="{% static 'bootstrap_icons/css/bootstrap_icons.css' %}">
```
## Configuration
You can specify the source from which the icons are loaded:
```
BS_ICONS_BASE_URL = 'https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/'
```
BS_ICONS_BASE_URL defaults to the latest boostrap-icons CDN that was available
when releasing this package. Change the URL to use an older or newer one.
To add custom icons to your app you need to set the path where these can be found.
The default setting is *custom-icons*, so you would add your icons
to */your-app/static/custom-icons/*.
```
BS_ICONS_CUSTOM_PATH = 'custom-icons'
```
### Configure Material Design Icons
Material Desing Icons are loaded from the default URL:
```
MD_ICONS_BASE_URL = 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.2.96/'
```
You can change it to your desired location by overriding this setting.
### Configure icon cache
To avoid fetching icons multiple times, configure the icon cache directory:
```
BS_ICONS_CACHE = os.path.join(STATIC_ROOT, 'icon_cache')
```
This will ensure that icons will be loaded only once with their individual svg properties
and stored to a local file. On each subsequent use the icon will be simply loaded from file.
### Configure icon not found return
In case icons are not found you can configure, what to display:
```
BS_ICONS_NOT_FOUND = f"Icon <{icon_path}> does not exist"
```
This shows the error message if you for example misspelled an icon name.
If you're running your app offline you may want to display some value that has the same size as the icon:
```
BS_ICONS_NOT_FOUND = '<?xml version="1.0" ?>\
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="red" class="bi bi-x-circle" viewBox="0 0 16 16">\
<path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>\
<path d="M4.646 4.646a.5.5 0 0 1 .708 0L8 7.293l2.646-2.647a.5.5 0 0 1 .708.708L8.707 8l2.647 2.646a.5.5 0 0 1-.708.708L8 8.707l-2.646 2.647a.5.5 0 0 1-.708-.708L7.293 8 4.646 5.354a.5.5 0 0 1 0-.708z"/>\
</svg>'
```
## License
This project is licensed under the MIT License - see the
[LICENSE](https://github.com/christianwgd/django-bootstrap-icons/blob/master/LICENCE) file for details
## Acknowledgments
* Thanks to [Bootstrap Icons](https://icons.getbootstrap.com)!
* Thanks to [Material Design Icons](https://google.github.io/material-design-icons/)!
## Releases
- see CHANGELOG.md
## Run the sample app
```
git clone https://github.com/christianwgd/django-bootstrap-icons.git
cd django-bootstrap-icons
<create a virtual environment with your preferred tooling (virtualenv/venv/pipenv)
pip install -U -r requirements.txt
python manage.py migrate
python manage.py runserver
```
Output of the example app:
## Run the tests
Setup the sample app (see above)
```
python manage.py test
```
Raw data
{
"_id": null,
"home_page": "https://github.com/christianwgd/django-bootstrap-icons",
"name": "django-bootstrap-icons",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "django,bootstrap,icons,templatetags",
"author": "Christian Wiegand",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/08/b2/986a7943973c5ec9b36a75e60d185aa93c123025f852343eb5f630ec745b/django-bootstrap-icons-0.8.7.tar.gz",
"platform": null,
"description": "# django-bootstrap-icons\n\n\n\n[](https://github.com/christianwgd/django-bootstrap-icons/actions/workflows/django-test.yml)\n[](https://github.com/astral-sh/ruff)\n[](https://codecov.io/gh/christianwgd/django-bootstrap-icons)\n\nA quick way to add [Bootstrap Icons](https://icons.getbootstrap.com) with Django \ntemplate tags.\n\nEmbed bootstrap svg icons in your django templates with the possibility for styling \nand sizing.\n\n## Installing\n\n`django-bootstrap-icons` can be found on pypi. Run `pip install django-bootstrap-icons` \nto install the package on your machine or in your virtual environment.\n\n## Getting Started\n\nUsing django-bootstrap-icons is easy. First, add the `django_bootstrap_icons` \nDjango app in your settings file.\n\n```\nINSTALLED_APPS = [\n 'django_bootstrap_icons'\n]\n```\n\nAlso, load the tag library in your template file:\n\n```\n{% load bootstrap_icons %}\n```\n\nThen, add an icon with the following tag. Give the icon's name as the \nfirst parameter, and that's all that's required:\n\n```\n{% bs_icon 'alarm' %}\n```\n\n### Icon sizes\n\nYou can size the icons by setting the size parameter:\n\n```\n{% bs_icon 'alarm' size='1.5em' %}\n```\n\n### Icon styling\n\nSet the color of an icon by specifying the color parameter:\n\n```\n{% bs_icon 'alarm' color='red' %}\n```\n\nFor further styling, you can add extra css classes:\n\n```\n{% bs_icon 'alarm' extra_classes=\"your-classname1 your-classname2\" %}\n```\n\n#### Vertical alignment\n\nBy default, all sgv bootstrap icons are vertical aligned to the middle. Sometimes this is \nnot appropriate, especially when rendering beside text. To align with text *django-bootstrap-icons*\nprovides some css classes to set the desired vertical alignment. \n\nInclude the css file into your template\n\n```\n<link rel=\"stylesheet\" href=\"{% static 'bootstrap_icons/css/bootstrap_icons.css' %}\">\n```\n\nand add the class to the *extra_classes* parameter\n\n```\n{% bs_icon 'alarm' extra_classes=\"bi-valign-bottom\" %}\n```\n\nThe following classes are available:\n\n```\n.bi-valign-default /* This is a compromise also provided by bootstrap\n for the icon font. The value is vertical-align: -.125em; \n (see https://github.com/twbs/icons/issues/601 for details) */\n.bi-valign-middle /* this is the default from bootstrap for svg */\n.bi-valign-bottom\n.bi-valign-text-top\n.bi-valign-text-bottom\n```\n\nIf you have included the django-bootstrap-icons css, the default alignment will be to \nthe values from \".bi-valign-default\", so no need to add a class explicitly.\n \n### Custom icons\nThere's a template tag for your custom icons. Store the custom icons in some \nstatic directory. SET the BS_ICONS_CUSTOM_PATH setting to point to that static directory.\n\n```\n{% custom_icon 'your-custom-svg-name' %}\n```\n\nThe custom template accepts the same parameter as the bootstrap icon template.\n\nIn fact you could download the bootstrap icons from bootstrap, store them in \nyour static files and use them with the custom_icon template tag. This would \navoid the use of CDN completely. \n\n### Material Design Icons\n\n*django-bootstrap-icons* works fine with Material Design Icons. There is a template\ntag for MDI:\n\n```\n{% md_icon 'alarm' %}\n```\n\nMaterial Design Icons get some additional css classes *mdi* and *mdi-<icon-name>* to \nstyle them globally.\n\nTo use Material Design Icons side-by-side with bootstrap icons *django-bootstrap-icons* \nmakes some adjustments in rendering the icons:\n\n* The base size of Material Design Icons is larger than the size of bootstrap icons. \n For the default size (no size attribute given), *django-bootstrap* icons are resized.\n If you want to have the same size as Bootstrap Icons, set them to a size factor of 1.25.\n If Bootstrap Icon is of size 2em, set Material Icon to 2.5em. (Although the base size \n in mdi svgs is 24 the real size of the icon is 20 because of some empty space, that\n surrounds the icons).\n \n* Because of that empty white space of the MDI (sort of some internal \"padding\" in svg)\n you need to include the django-bootstrap-icons css file to make some adjustments to \n the alignment.\n\n```\n<link rel=\"stylesheet\" href=\"{% static 'bootstrap_icons/css/bootstrap_icons.css' %}\">\n```\n\n## Configuration\n\nYou can specify the source from which the icons are loaded:\n\n```\nBS_ICONS_BASE_URL = 'https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/'\n```\n\nBS_ICONS_BASE_URL defaults to the latest boostrap-icons CDN that was available \nwhen releasing this package. Change the URL to use an older or newer one.\n\nTo add custom icons to your app you need to set the path where these can be found. \nThe default setting is *custom-icons*, so you would add your icons \nto */your-app/static/custom-icons/*.\n\n```\nBS_ICONS_CUSTOM_PATH = 'custom-icons'\n```\n\n### Configure Material Design Icons\n\nMaterial Desing Icons are loaded from the default URL:\n\n```\nMD_ICONS_BASE_URL = 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.2.96/'\n```\n\nYou can change it to your desired location by overriding this setting. \n\n### Configure icon cache\n\nTo avoid fetching icons multiple times, configure the icon cache directory:\n\n```\nBS_ICONS_CACHE = os.path.join(STATIC_ROOT, 'icon_cache')\n```\n\nThis will ensure that icons will be loaded only once with their individual svg properties \nand stored to a local file. On each subsequent use the icon will be simply loaded from file.\n\n### Configure icon not found return\n\nIn case icons are not found you can configure, what to display:\n\n```\nBS_ICONS_NOT_FOUND = f\"Icon <{icon_path}> does not exist\"\n```\n\nThis shows the error message if you for example misspelled an icon name.\n\nIf you're running your app offline you may want to display some value that has the same size as the icon:\n\n```\nBS_ICONS_NOT_FOUND = '<?xml version=\"1.0\" ?>\\\n<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" fill=\"red\" class=\"bi bi-x-circle\" viewBox=\"0 0 16 16\">\\\n\t<path d=\"M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z\"/>\\\n\t<path d=\"M4.646 4.646a.5.5 0 0 1 .708 0L8 7.293l2.646-2.647a.5.5 0 0 1 .708.708L8.707 8l2.647 2.646a.5.5 0 0 1-.708.708L8 8.707l-2.646 2.647a.5.5 0 0 1-.708-.708L7.293 8 4.646 5.354a.5.5 0 0 1 0-.708z\"/>\\\n</svg>'\n```\n\n## License\n\nThis project is licensed under the MIT License - see the \n[LICENSE](https://github.com/christianwgd/django-bootstrap-icons/blob/master/LICENCE) file for details\n\n## Acknowledgments\n\n* Thanks to [Bootstrap Icons](https://icons.getbootstrap.com)!\n* Thanks to [Material Design Icons](https://google.github.io/material-design-icons/)!\n\n## Releases\n- see CHANGELOG.md\n\n## Run the sample app\n```\ngit clone https://github.com/christianwgd/django-bootstrap-icons.git\ncd django-bootstrap-icons\n<create a virtual environment with your preferred tooling (virtualenv/venv/pipenv)\npip install -U -r requirements.txt\npython manage.py migrate\npython manage.py runserver\n```\n\nOutput of the example app: \n![example](https://github.com/christianwgd/django-bootstrap-icons/blob/master/sample-app-result.png \"Sample App Output\")\n\n## Run the tests\nSetup the sample app (see above)\n```\npython manage.py test\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A quick way to add Bootstrap Icons with Django template tags.",
"version": "0.8.7",
"project_urls": {
"Homepage": "https://github.com/christianwgd/django-bootstrap-icons"
},
"split_keywords": [
"django",
"bootstrap",
"icons",
"templatetags"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e65ad86a0f62e36e81e28d217261a6ca47835cb1b603709032e48ff491671168",
"md5": "3ded7d640ceba594853ee08501c92ed0",
"sha256": "40ec283487033aadccbb69b733d5d5d6fdc5117b302580659b2d2535304ddfef"
},
"downloads": -1,
"filename": "django_bootstrap_icons-0.8.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ded7d640ceba594853ee08501c92ed0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7878,
"upload_time": "2023-12-05T10:08:03",
"upload_time_iso_8601": "2023-12-05T10:08:03.592731Z",
"url": "https://files.pythonhosted.org/packages/e6/5a/d86a0f62e36e81e28d217261a6ca47835cb1b603709032e48ff491671168/django_bootstrap_icons-0.8.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "08b2986a7943973c5ec9b36a75e60d185aa93c123025f852343eb5f630ec745b",
"md5": "df6fbf616256335686b396881f00106d",
"sha256": "d4367bfd38f2605817284e365922c295267225c07a57596e4c66d7dd19a5700a"
},
"downloads": -1,
"filename": "django-bootstrap-icons-0.8.7.tar.gz",
"has_sig": false,
"md5_digest": "df6fbf616256335686b396881f00106d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8294,
"upload_time": "2023-12-05T10:08:05",
"upload_time_iso_8601": "2023-12-05T10:08:05.174040Z",
"url": "https://files.pythonhosted.org/packages/08/b2/986a7943973c5ec9b36a75e60d185aa93c123025f852343eb5f630ec745b/django-bootstrap-icons-0.8.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-05 10:08:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "christianwgd",
"github_project": "django-bootstrap-icons",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-bootstrap-icons"
}
JSON
