Settings

The django-bootstrap5 has some pre-configured settings.

They can be modified by adding a dict variable called BOOTSTRAP5 in your settings.py and customizing the values you want;

The BOOTSTRAP5 dict variable contains these settings and defaults:

# Default settings
BOOTSTRAP5 = {

    # The complete URL to the Bootstrap CSS file.
    # Note that a URL can be either a string
    # ("https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css"),
    # or a dict with keys `url`, `integrity` and `crossorigin` like the default value below.
    "css_url": {
        "url": "https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css",
        "integrity": "sha384-gH2yIJqKdNHPEq0n4Mqa/HGKIhSkIHeL5AyhkYV8i59U5AR6csBvApHHNl/vI1Bx",
        "crossorigin": "anonymous",
    },

    # The complete URL to the Bootstrap bundle JavaScript file.
    "javascript_url": {
        "url": "https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/js/bootstrap.bundle.min.js",
        "integrity": "sha384-A3rJD856KowSb7dwlZdYEkO39Gagi7vIsF0jrRAoQmDKKtQBHUuLZ9AsSv4jD4Xa",
        "crossorigin": "anonymous",
    },

    # The complete URL to the Bootstrap CSS theme file (None means no theme).
    "theme_url": None,

    # Color mode (None means do not set color mode).
    "color_mode": None,

    # Put JavaScript in the HEAD section of the HTML document (only relevant if you use bootstrap5.html).
    'javascript_in_head': False,

    # Default layout for forms and fields.
    # Can be floating, horizontal, or inline. Can be overridden per call with the "layout" argument.
    'layout': '',

    # Wrapper class for non-inline fields.
    # The default value "mb-3" is the spacing as used by Bootstrap 5 example code.
    'wrapper_class': 'mb-3',

    # Wrapper class for inline fields.
    # The default value is empty, as Bootstrap5 example code doesn't use a wrapper class.
    'inline_wrapper_class': '',

    # CSS class for the label element.
    'label_class': '',

    # Field class for inline fields.
    # the default value is "col-12". This class will combined with `inline_wrapper_class`.
    'inline_field_class': 'col-auto',

    # Label class to use in horizontal forms.
    'horizontal_label_class': 'col-sm-2',

    # Field class to use in horizontal forms.
    'horizontal_field_class': 'col-sm-10',

    # Field class used for horizontal fields without a label.
    'horizontal_field_offset_class': 'offset-sm-2',

    # HTML attributes with any of these prefixes will have underscores converted to hyphens.
    "hyphenate_attribute_prefixes": ["data"],

    # Set placeholder attributes to label if no placeholder is provided.
    'set_placeholder': True,

    # Class to indicate required field (better to set this in your Django form).
    'required_css_class': '',

    # Class to indicate field has one or more errors (better to set this in your Django form).
    'error_css_class': '',

    # Class to indicate success, meaning the field has valid input (better to set this in your Django form).
    'success_css_class': '',

    # Enable or disable Bootstrap 5 server side validation classes (separate from the indicator classes above).
    'server_side_validation': True,

    # Renderers (only set these if you have studied the source and understand the inner workings).
    'formset_renderers':{
        'default': 'django_bootstrap5.renderers.FormsetRenderer',
    },
    'form_renderers': {
        'default': 'django_bootstrap5.renderers.FormRenderer',
    },
    'field_renderers': {
        'default': 'django_bootstrap5.renderers.FieldRenderer',
    },
}

Serving Bootstrap from your own static files

To serve Bootstrap from your own staticfiles app instead of a CDN, point the URL settings at your static files. The URL has to be resolved when the tag renders, not when the settings module is imported, because a storage backend such as ManifestStaticFilesStorage only knows the hashed filename after collectstatic has run. Wrap static() in lazy() to get that:

from django.templatetags.static import static
from django.utils.functional import lazy

lazy_static = lazy(static, str)

BOOTSTRAP5 = {
    "css_url": lazy_static("css/bootstrap.min.css"),
    "javascript_url": lazy_static("js/bootstrap.bundle.min.js"),
}

The dict form works the same way, for when you want to set other attributes alongside the URL:

BOOTSTRAP5 = {
    "css_url": {"url": lazy_static("css/bootstrap.min.css"), "crossorigin": "anonymous"},
}

Drop integrity when you serve the files yourself. The hash in the default settings is over the CDN’s file, not over your copy, and ManifestStaticFilesStorage rewrites the url() references inside the CSS to hashed names, so the content changes again.

Unused settings

A key in BOOTSTRAP5 that this package does not read is ignored. That is a problem when a setting used to exist and was removed, or when a settings dict is carried over from django-bootstrap3 or django-bootstrap4: the key goes on looking effective while doing nothing.

A system check reports those keys, so they show up in manage.py check, in runserver and in CI:

?: (django_bootstrap5.W001) BOOTSTRAP5['jquery_url'] has no effect: not a
django-bootstrap5 setting; Bootstrap 5 does not use jQuery.

If you deliberately keep extra keys in the dict, silence it with:

SILENCED_SYSTEM_CHECKS = ["django_bootstrap5.W001"]