Use Macros¶

These macros will help you to generate Bootstrap-markup codes quickly and easily.

render_nav_item()¶

Render a Bootstrap nav item.

Example¶

{% from 'bootstrap4/nav.html' import render_nav_item %}

<nav class="navbar navbar-expand-lg navbar-light bg-light">
    <div class="navbar-nav mr-auto">
        {{ render_nav_item('index', 'Home') }}
        {{ render_nav_item('explore', 'Explore') }}
        {{ render_nav_item('about', 'About') }}
    </div>
</nav>

API¶

render_nav_item(endpoint, text, _badge='', _use_li=False, **kwargs)¶

Parameters:

endpoint – The endpoint used to generate URL.
text – The text that will displayed on the item.
_badge – Badge text.
_use_li – Default to generate <a></a>, if set to True, it will generate <li><a></a></li>.
kwargs – Additional keyword arguments pass to url_for().

render_field()¶

Render a form input for form field created by Flask-WTF/WTForms.

Example¶

{% from 'bootstrap4/form.html' import render_field %}

<form method="post">
    {{ form.csrf_token() }}
    {{ render_field(form.username) }}
    {{ render_field(form.password) }}
    {{ render_field(form.submit) }}
</form>

You can pass any HTTP attributes as extra keyword arguments like class or placeholder:

Notice that a placeholder is only allowed by W3C validation when the input type is email, number, password, search, tel, text or url. However, it is possible to use a placeholder for input types such as datetime.

{% from 'bootstrap4/form.html' import render_field %}

<form method="post">
    {{ form.csrf_token() }}
    {{ render_field(form.username, class='myClass') }}
    {{ render_field(form.password, placeholder='Your Password') }}
    {{ render_field(form.submit) }}
</form>

Notice the class value here will overwrite the render_kw={'class': '...'} you defined in the form class. Bootstrap-Flask will combine the class value you passed with the class key of the render_kw dict or the class keyword arguments with Bootstrap classes.

API¶

render_field(field, form_type='basic', horizontal_columns=('lg', 2, 10), button_style='', button_size='', button_map={}, form_group_classes='')¶

Parameters:

field – The form field (attribute) to render.
form_type – One of basic, inline or horizontal. See the Bootstrap docs for details on different form layouts.
horizontal_columns – When using the horizontal layout, layout forms like this. Must be a 3-tuple of (column-type, left-column-size, right-column-size).
button_style – Set button style for SubmitField. Accept Bootstrap button style name (i.e. primary, secondary, outline-success, etc.), default to primary (e.g. btn-primary). This will overwrite config BOOTSTRAP_BTN_STYLE.
button_size – Set button size for SubmitField. Accept Bootstrap button size name: sm, md, lg, block, default to md. This will overwrite config BOOTSTRAP_BTN_SIZE.
form_group_classes – Bootstrap 5 only (bootstrap5/form.html). You can use this parameter to change the form group classes, it will read the config BOOTSTRAP_FORM_GROUP_CLASSES first (the default value is mb-3).

Tip

See Form Button Customization and Form Checkbox Customization to learn more on customizations.

render_form()¶

Render a complete form element for form object created by Flask-WTF/WTForms.

Example¶

{% from 'bootstrap4/form.html' import render_form %}

{{ render_form(form) }}

API¶

render_form(form, action='', method='post', extra_classes=None, role='form', form_type='basic', horizontal_columns=('lg', 2, 10), enctype=None, button_style='', button_size='', button_map={}, id='', novalidate=False, render_kw={}, form_group_classes='', form_inline_classes='')¶

Parameters:

form – The form to output.
action – The URL to receive form data.
method – <form> method attribute.
extra_classes – The classes to add to the <form>.
role – <form> role attribute.
form_type – One of basic, inline or horizontal. See the Bootstrap docs for details on different form layouts.
horizontal_columns – When using the horizontal layout, layout forms like this. Must be a 3-tuple of (column-type, left-column-size, right-column-size).
enctype – <form> enctype attribute. If None, will automatically be set to multipart/form-data if a FileField or MultipleFileField is present in the form.
button_style – Set button style for SubmitField. Accept Bootstrap button style name (i.e. primary, secondary, outline-success, etc.), default to primary (e.g. btn-primary). This will overwrite config BOOTSTRAP_BTN_STYLE.
button_size – Set button size for SubmitField. Accept Bootstrap button size name: sm, md, lg, block, default to md. This will overwrite config BOOTSTRAP_BTN_SIZE.
button_map – A dictionary, mapping button field name to Bootstrap button style names. For example, {'submit': 'success'}. This will overwrite button_style and BOOTSTRAP_BTN_STYLE.
id – The <form> id attribute.
novalidate – Flag that decide whether add novalidate class in <form>.
render_kw – A dictionary, specifying custom attributes for the <form> tag.
form_group_classes – Bootstrap 5 only (bootstrap5/form.html). You can use this parameter to change the form group classes, it will read the config BOOTSTRAP_FORM_GROUP_CLASSES first (the default value is mb-3).
form_inline_classes – Bootstrap 5 only (bootstrap5/form.html). You can use this parameter to change the form inline classes, it will read the config BOOTSTRAP_FORM_INLINE_CLASSES first (the default value is row row-cols-lg-auto g-3 align-items-center).

Tip

See Form Button Customization to learn how to customize form buttons.

render_hidden_errors()¶

Render error messages for hidden form field (wtforms.HiddenField).

Example¶

{% from 'bootstrap4/form.html' import render_field, render_hidden_errors %}

<form method="post">
    {{ form.hidden_tag() }}
    {{ render_hidden_errors(form) }}
    {{ render_field(form.username) }}
    {{ render_field(form.password) }}
    {{ render_field(form.submit) }}
</form>

API¶

render_hidden_errors(form)¶

Parameters:: form – Form whose errors should be rendered.

render_form_row()¶

Render a row of a grid form with the given fields.

Example¶

{% from 'bootstrap4/form.html' import render_form_row %}

<form method="post">
    {{ form.csrf_token() }}
    {{ render_form_row([form.username, form.password]) }}
    {{ render_form_row([form.remember]) }}
    {{ render_form_row([form.submit]) }}
    {# Custom col which should use class col-md-2, and the others the defaults: #}
    {{ render_form_row([form.title, form.first_name, form.surname], col_map={'title': 'col-md-2'}) }}
    {# Custom col which should use class col-md-2 and modified col class for the default of the other fields: #}
    {{ render_form_row([form.title, form.first_name, form.surname], col_class_default='col-md-5', col_map={'title': 'col-md-2'}) }}
</form>

API¶

render_form_row(fields, row_class='row/form-row', col_class_default='col', col_map={}, button_style='', button_size='', button_map={}, form_group_classes='', form_type='basic', horizontal_columns=('lg', 2, 10))¶

Parameters:

fields – An iterable of fields to render in a row.
row_class – Class to apply to the div intended to represent the row, like form-row (Bootstrap 4) or row (Bootstrap 5).
col_class_default – The default class to apply to the div that represents a column if nothing more specific is said for the div column of the rendered field.
col_map – A dictionary, mapping field.name to a class definition that should be applied to the div column that contains the field. For example: col_map={'username': 'col-md-2'}).
button_style – Set button style for SubmitField. Accept Bootstrap button style name (i.e. primary, secondary, outline-success, etc.), default to primary (e.g. btn-primary). This will overwrite config BOOTSTRAP_BTN_STYLE.
button_size – Set button size for SubmitField. Accept Bootstrap button size name: sm, md, lg, block, default to md. This will overwrite config BOOTSTRAP_BTN_SIZE.
button_map – A dictionary, mapping button field name to Bootstrap button style names. For example, {'submit': 'success'}. This will overwrite button_style and BOOTSTRAP_BTN_STYLE.
form_group_classes – Bootstrap 5 only (bootstrap5/form.html). You can use this parameter to change the form group classes, it will read the config BOOTSTRAP_FORM_GROUP_CLASSES first (the default value is mb-3).
form_type – One of basic, inline or horizontal. See the Bootstrap docs for details on different form layouts.
horizontal_columns – When using the horizontal layout, layout forms like this. Must be a 3-tuple of (column-type, left-column-size, right-column-size).

Tip

See Form Button Customization to learn how to customize form buttons.

render_pagination()¶

Render a standard pagination for query pagination object created by Flask-SQLAlchemy.

Example¶

{% from 'bootstrap4/pagination.html' import render_pagination %}

{{ render_pagination(pagination) }}

API¶

render_pagination(pagination, endpoint=None, prev='«', next='»', ellipses='…', size=None, args={}, fragment='', align='', **kwargs)¶

Parameters:

pagination – Pagination instance.
endpoint – Which endpoint to call when a page number is clicked. url_for() will be called with the given endpoint and a single parameter, page. If None, uses the requests current endpoint.
prev – Symbol/text to use for the “previous page” button. If None, the button will be hidden.
next – Symbol/text to use for the “next page” button. If None, the button will be hidden.
ellipses – Symbol/text to use to indicate that pages have been skipped. If None, no indicator will be printed.
size – Can be ‘sm’ or ‘lg’ for smaller/larger pagination.
args – Additional arguments passed to url_for(). If endpoint is None, uses args and view_args.
fragment – Add URL fragment into link, such as #comment.
align – The align of the pagination. Can be ‘left’, ‘center’ or ‘right’, default to ‘left’.
kwargs – Extra attributes for the <ul>-element.

render_static()¶

Render a resource reference code (i.e. <link>, <script>).

Example¶

{% from 'bootstrap4/utils.html' import render_static %}

{{ render_static('css', 'style.css') }}

API¶

render_static(type, filename_or_url, local=True)¶

Parameters:

type – Resources type, one of css, js, icon.
filename_or_url – The path of the file (relative to the static folder), or the full URL when local set to False.
local – Load local resources or from the passed URL.

render_messages()¶

Render Bootstrap alerts for flash messages send by flask.flash().

Example¶

Flash the message in your view function with flash(message, category):

from flask import flash

@app.route('/test')
def test():
    flash('a info message', 'info')
    flash('a danger message', 'danger')
    return your_template

Render the messages in your base template (normally below the navbar):

{% from 'bootstrap4/utils.html' import render_messages %}

<nav>...</nav>
{{ render_messages() }}
<main>...</main>

API¶

render_messages(messages=None, container=False, transform={...}, default_category=config.BOOTSTRAP_MSG_CATEGORY, dismissible=False, dismiss_animate=False)¶

Parameters:

messages – The messages to show. If not given, default to get from flask.get_flashed_messages(with_categories=True).
container – If true, will output a complete <div class="container"> element, otherwise just the messages each wrapped in a <div>.
transform – A dictionary of mappings for categories. Will be looked up case-insensitively. Default maps all Python loglevel names to Bootstrap CSS classes.
default_category – If a category does not has a mapping in transform, it is passed through unchanged. default_category will be used when category is empty.
dismissible – If true, will output a button to close an alert. For fully functioning dismissible alerts, you must use the alerts JavaScript plugin.
dismiss_animate – If true, will enable dismiss animate when click the dismiss button.

When you call flash('message', 'category'), there are 8 category options available, mapping to Bootstrap’s alerts type:

primary, secondary, success, danger, warning, info, light, dark.

If you want to use HTML in your message body, just wrapper your message string with flask.Markup to tell Jinja it’s safe:

from flask import flash, Markup

@app.route('/test')
def test():
    flash(Markup('a info message with a link: <a href="/">Click me!</a>'), 'info')
    return your_template

render_table()¶

Render a Bootstrap table with given data.

Example¶

@app.route('/test')
def test():
    data = Message.query.all()
    return render_template('test.html', data=data)

{% from 'bootstrap4/table.html' import render_table %}

{{ render_table(data) }}

API¶

render_table(data, titles=None, primary_key='id', primary_key_title='#', caption=None, table_classes=None, header_classes=None, responsive=False, responsive_class='table-responsive', safe_columns=None, urlize_columns=None, show_actions=False, actions_title='Actions', model=None, custom_actions=None, view_url=None, edit_url=None, delete_url=None, new_url=None)¶

Parameters:

data – An iterable of data objects to render. Can be dicts or class objects.
titles – An iterable of tuples of the format (prop, label) e.g [('id', '#')], if not provided, will automatically detect on provided data, currently only support SQLAlchemy object.
primary_key – Primary key identifier for a single row, default to id.
primary_key_title – Primary key title for a single row, default to #.
caption – A caption to attach to the table.
table_classes – A string of classes to apply to the table (e.g 'table-small table-dark').
header_classes – A string of classes to apply to the table header (e.g 'thead-dark').
responsive – Whether to enable/disable table responsiveness.
responsive_class – The responsive class to apply to the table. Default is 'table-responsive'.
safe_columns – Tuple with columns names to render HTML safe using |safe. Has priority over urlize_columns parameter. Default is None.
urlize_columns – Tuple with column names to render with HTML link on each URL using |urlize. Is overruled by safe_columns parameter. Default is None. WARNING: Only use this for sanitized user data to prevent XSS attacks.
show_actions – Whether to display the actions column. Default is False.
model – The model used to build custom_action, view, edit, delete URLs.
actions_title – Title for the actions column header. Default is 'Actions'.
custom_actions – A list of tuples for creating custom action buttons, where each tuple contains (‘Title Text displayed on hover’, ‘bootstrap icon name’, ‘URL tuple or fixed URL string’) (e.g. [('Run', 'play-fill', ('run_report', [('report_id', ':id')]))]).
view_url – URL string or URL tuple in ('endpoint', [('url_parameter_name', ':db_model_fieldname')]) to use for the view action.
edit_url – URL string or URL tuple in ('endpoint', [('url_parameter_name', ':db_model_fieldname')]) to use for the edit action.
delete_url – URL string or URL tuple in ('endpoint', [('url_parameter_name', ':db_model_fieldname')]) to use for the delete action.
new_url – URL string to use for the create action (new in version 1.6.0).

To set the URLs for table actions, you will need to pass either a fixed URL string or an URL tuple in the form of ('endpoint', [('url_parameter_name', ':db_model_fieldname')]):

endpoint: endpoint of the view, normally the name of the view function
[('url_parameter_name', ':db_model_fieldname')]: a list of two-element tuples, the tuple should contain the URL parameter name and the corresponding field name in the database model (starts with a : mark to indicate it’s a variable, otherwise it will becomes a fixed value). db_model_fieldname may also contain dots to access relationships and their fields (e.g. user.name).

Remember to set the model when setting this URLs, so that Bootstrap-Flask will know where to get the actual value when building the URL.

For example, for the view below:

class Message(Model):
    id = Column(primary_key=True)

@app.route('/messages/<int:message_id>')
def view_message(message_id):
    pass

To pass the URL point to this view for view_url, the value will be: view_url=('view_message', [('message_id', ':id')]). Here is the full example:

@app.route('/test')
def test():
    data = Message.query.all()
    return render_template('test.html', data=data, Message=Message)

{% from 'bootstrap4/table.html' import render_table %}

{{ render_table(data, model=Message, view_url=('view_message', [('message_id', ':id')])) }}

The following arguments are expect to accpet an URL tuple:

custom_actions
view_url
edit_url
delete_url

When setting the delete_url, you will also need to enable the CSRFProtect extension provided by Flask-WTF, so that the CSRF protection can be added to the delete button:

$ pip install flask-wtf

from flask_wtf import CSRFProtect

csrf = CSRFProtect(app)

By default, it will enable the CSRF token check for all the POST requests, read more about this extension in its documentation.

render_icon()¶

Render a Bootstrap icon.

Example¶

{% from 'bootstrap4/utils.html' import render_icon %}

{{ render_icon('heart') }}

API¶

render_icon(name, size=config.BOOTSTRAP_ICON_SIZE, color=config.BOOTSTRAP_ICON_COLOR, title=None, desc=None)¶

Parameters:

name – The name of icon, you can find all available names at Bootstrap Icon.
size – The size of icon, you can pass any vaild size value (e.g. 32/'32px', 1.5em, etc.), default to use configuration BOOTSTRAP_ICON_SIZE (default value is ‘1em’).
color – The color of icon, follow the context with currentColor if not set. Accept values are Bootstrap style name (one of ['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark', 'muted']) or any valid color string (e.g. 'red', '#ddd' or '(250, 250, 250)'), default to use configuration BOOTSTRAP_ICON_COLOR (default value is None).
title – The title of the icon for accessibility support.
desc – The description of the icon for accessibility support.

Use Macros¶

render_nav_item()¶

Example¶

API¶

render_field()¶

Example¶

API¶

render_form()¶

Example¶

API¶

render_hidden_errors()¶

Example¶

API¶

render_form_row()¶

Example¶

API¶

render_static()¶

Example¶

API¶

render_messages()¶

Example¶

API¶

render_table()¶

Example¶

API¶

render_icon()¶

Example¶

API¶

Bootstrap-Flask

Donate

Links

Table of Contents

Related Topics

Use Macros¶

render_nav_item()¶

Example¶

API¶

render_breadcrumb_item()¶

Example¶

API¶

render_field()¶

Example¶

API¶

render_form()¶

Example¶

API¶

render_hidden_errors()¶

Example¶

API¶

render_form_row()¶

Example¶

API¶

render_pager()¶

Example¶

API¶

render_pagination()¶

Example¶

API¶

render_static()¶

Example¶

API¶

render_messages()¶

Example¶

API¶

render_table()¶

Example¶

API¶

render_icon()¶

Example¶

API¶