Basic Usage¶
Installation¶
$ pip install bootstrap-flask
This project can’t work with Flask-Bootstrap at the same time. If you have already installed Flask-Bootstrap in the same Python enviroment, you have to uninstall it and then reinstall this project:
$ pip uninstall flask-bootstrap bootstrap-flask
$ pip install bootstrap-flask
Tip
See Migrate from Flask-Bootstrap to learn how to migrate from Flask-Bootstrap.
Initialization¶
from flask_bootstrap import Bootstrap4
from flask import Flask
app = Flask(__name__)
bootstrap = Bootstrap4(app)
If you want to use Bootstrap 5, import and instanzlize the Bootstrap5
class instead:
from flask_bootstrap import Bootstrap5
from flask import Flask
app = Flask(__name__)
bootstrap = Bootstrap5(app)
Resources Helpers¶
Bootstrap-Flask provides two helper functions to load Bootstrap resources in the template:
bootstrap.load_css()
and bootstrap.load_js()
.
Call it in your base template, for example:
<head>
....
{{ bootstrap.load_css() }}
</head>
<body>
...
{{ bootstrap.load_js() }}
</body>
You can pass version
to pin the Bootstrap version you want to use.
It defaults to load files from CDN. Set BOOTSTRAP_SERVE_LOCAL
to True
to use built-in local files. However, these methods are optional, you can also write <href></href>
and <script></script>
tags to include Bootstrap resources (from your static
folder or CDN) manually by yourself.
If you want to apply a strict Content Security Policy (CSP), you can pass nonce
to bootstrap.load_js()
.
E.g. if using Talisman it can be called with bootstrap.load_js(nonce=csp_nonce())
.
Starter template¶
For reasons of flexibility, Bootstrap-Flask doesn’t include built-in base templates (this may change in the future). For now, you have to create a base template yourself. Be sure to use an HTML5 doctype and include a viewport meta tag for proper responsive behaviors. Here’s an example base template:
<!doctype html>
<html lang="en">
<head>
{% block head %}
<!-- Required meta tags -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
{% block styles %}
<!-- Bootstrap CSS -->
{{ bootstrap.load_css() }}
{% endblock %}
<title>Your page title</title>
{% endblock %}
</head>
<body>
<!-- Your page content -->
{% block content %}{% endblock %}
{% block scripts %}
<!-- Optional JavaScript -->
{{ bootstrap.load_js() }}
{% endblock %}
</body>
</html>
Use this in your templates folder (suggested names are base.html
or layout.html
etc.), and inherit it in child templates. See Template Inheritance for more details on inheritance.
Macros¶
Macro |
Templates Path |
Description |
---|---|---|
render_field() |
bootstrap4/form.html |
Render a WTForms form field |
render_form() |
bootstrap4/form.html |
Render a WTForms form |
render_form_row() |
bootstrap4/form.html |
Render a row of a grid form |
render_hidden_errors() |
bootstrap4/form.html |
Render error messages for hidden form field |
render_pager() |
bootstrap4/pagination.html |
Render a basic Flask-SQLAlchemy pagniantion |
render_pagination() |
bootstrap4/pagination.html |
Render a standard Flask-SQLAlchemy pagination |
render_nav_item() |
bootstrap4/nav.html |
Render a navigation item |
render_breadcrumb_item() |
bootstrap4/nav.html |
Render a breadcrumb item |
render_static() |
bootstrap4/utils.html |
Render a resource reference code (i.e. |
render_messages() |
bootstrap4/utils.html |
Render flashed messages send by flash() function |
render_icon() |
bootstrap4/utils.html |
Render a Bootstrap icon |
render_table() |
bootstrap4/table.html |
Render a table with given data |
How to use these macros? It’s quite simple, just import them from the corresponding path and call them like any other macro:
{% from 'bootstrap4/form.html' import render_form %}
{{ render_form(form) }}
Notice we import Bootstrap 4 macros from the path bootstrap4/...
, if you are using Bootstrap 5, import them from
the bootstrap5/...
path instead:
{% from 'bootstrap5/form.html' import render_form %}
Go to the Use Macros page to see the detailed usage for these macros.
Run the Demo Application¶
Bootstrap-Flask provides a demo application that contains all the code snippets for the macros and the corresponding render output. See Run the demo application for the details.
Configurations¶
Configuration Variable |
Default Value |
Description |
---|---|---|
BOOTSTRAP_SERVE_LOCAL |
|
If set to |
BOOTSTRAP_BTN_STYLE |
|
Default form button style, will change to |
BOOTSTRAP_BTN_SIZE |
|
Default form button size |
BOOTSTRAP_ICON_SIZE |
|
Default icon size |
BOOTSTRAP_ICON_COLOR |
|
Default icon color, follow the context with |
BOOTSTRAP_BOOTSWATCH_THEME |
|
Bootswatch theme to use, see available themes at Bootswatch Themes |
BOOTSTRAP_MSG_CATEGORY |
|
Default flash message category |
BOOTSTRAP_TABLE_VIEW_TITLE |
|
Default title for view icon of table actions |
BOOTSTRAP_TABLE_EDIT_TITLE |
|
Default title for edit icon of table actions |
BOOTSTRAP_TABLE_DELETE_TITLE |
|
Default title for delete icon of table actions |
BOOTSTRAP_TABLE_NEW_TITLE |
|
Default title for new icon of table actions |
BOOTSTRAP_FORM_GROUP_CLASSES |
|
Default form group classes |
BOOTSTRAP_FORM_INLINE_CLASSES |
|
Default form inline classes |
Tip
See Form Button Customization to learn how to customize form buttons.