Repository files navigation

A quick way to addBootstrap Icons with Djangotemplate tags.

Embed bootstrap svg icons in your django templates with the possibility for stylingand sizing.

django-bootstrap-icons can be found on pypi. Runpip install django-bootstrap-iconsto install the package on your machine or in your virtual environment.

Using django-bootstrap-icons is easy. First, add thedjango_bootstrap_iconsDjango 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 thefirst parameter, and that's all that's required:

{% bs_icon 'alarm' %}

You can size the icons by setting the size parameter:

{% bs_icon 'alarm' size='1.5em' %}

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" %}

By default, all sgv bootstrap icons are vertical aligned to the middle. Sometimes this isnot appropriate, especially when rendering beside text. To align with textdjango-bootstrap-iconsprovides 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 theextra_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 tothe values from ".bi-valign-default", so no need to add a class explicitly.

There's a template tag for your custom icons. Store the custom icons in somestatic 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 inyour static files and use them with the custom_icon template tag. This wouldavoid the use of CDN completely.

django-bootstrap-icons works fine with Material Design Icons. There is a templatetag for MDI:

{% md_icon 'alarm' %}

Material Design Icons get some additional css classesmdi andmdi- tostyle them globally.

To use Material Design Icons side-by-side with bootstrap iconsdjango-bootstrap-iconsmakes 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 sizein mdi svgs is 24 the real size of the icon is 20 because of some empty space, thatsurrounds 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 tothe alignment.

<link rel="stylesheet" href="{% static 'bootstrap_icons/css/bootstrap_icons.css' %}">

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 availablewhen releasing this package. Change the URL to use an older or newer one.

You can also load icons from a local path. This will disable downloading iconsfrom BS_ICONS_BASE_URL:

BS_ICONS_BASE_PATH = 'node_modules/bootstrap-icons/'

To add custom icons to your app you need to set the path where these can be found.The default setting iscustom-icons, so you would add your iconsto/your-app/static/custom-icons/.

BS_ICONS_CUSTOM_PATH = 'custom-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.

You can also load icons from a local path. This will disable downloading iconsfrom MD_ICONS_BASE_URL:

MD_ICONS_BASE_PATH = 'node_modules/@mdi/svg'

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 propertiesand stored to a local file. On each subsequent use the icon will be simply loaded from file.

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" 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>'

This project is licensed under the MIT License - see theLICENSE file for details

• Thanks toBootstrap Icons!
• Thanks toMaterial Design Icons!

• see CHANGELOG.md

git clone https://github.com/christianwgd/django-bootstrap-icons.gitcd django-bootstrap-icons<create a virtual environment with your preferred tooling (virtualenv/venv/pipenv)pip install -U -r requirements.txtpython manage.py migratepython manage.py runserver

Output of the example app:

Setup the sample app (see above)

python manage.py test