API reference

class flask_nav.Nav(app=None)

The Flask-Nav extension.

Parameters:app – An optional Flask app to initialize.

Initialize an application.

Parameters:app – A Flask app.

Function decorator for navbar registration.

Convenience function, calls register_element() with id and the decorated function as elem.

Parameters:id – ID to pass on. If None, uses the decorated functions name.
register_element(id, elem)

Register navigational element.

Registers the given navigational element, making it available using the id id.

This means that inside any template, the registered element will be available as nav. id.

If elem is callable, any attempt to retrieve it inside the template will instead result in elem being called and the result being returned.

  • id – Id to register element with
  • elem – Element to register
renderer(id=None, force=True)

Class decorator for Renderers.

The decorated class will be added to the list of renderers kept by this instance that will be registered on the app upon app initialization.

  • id – Id for the renderer, defaults to the class name in snake case.
  • force – Whether or not to overwrite existing renderers.
flask_nav.get_renderer(app, id)

Retrieve a renderer.

  • appFlask application to look id up on
  • id – Internal renderer id-string to look up
flask_nav.register_renderer(app, id, renderer, force=True)

Registers a renderer on the application.

  • app – The Flask application to register the renderer on
  • id – Internal id-string for the renderer
  • renderer – Renderer to register
  • force – Whether or not to overwrite the renderer if a different one is already registered for id

An item that contains a link to a destination and a title.

class flask_nav.elements.Navbar(title, *items)

Top level navbar.

class flask_nav.elements.NavigationItem

Base for all items in a Navigation.

Every item inside a navigational view should derive from this class.

active = False

Indicates whether or not the item represents the currently active route

render(renderer=None, **kwargs)

Render the navigational item using a renderer.

Parameters:renderer – An object implementing the Renderer interface.
Returns:A markupsafe string with the rendered result.
class flask_nav.elements.RawTag(content, **attribs)

An item usually expressed by a single HTML tag.

  • title – The text inside the tag.
  • attribs – Attributes on the item.
class flask_nav.elements.Separator


A seperator inside the main navigational menu or a Subgroup. Not all renderers render these (or sometimes only inside Subgroups).

class flask_nav.elements.Subgroup(title, *items)

Nested substructure.

Usually used to express a submenu.

  • title – The title to display (i.e. when using dropdown-menus, this text will be on the button).
  • items – Any number of NavigationItem instances that make up the navigation element.
class flask_nav.elements.Text(text)

Label text.

Not a <label> text, but a text label nonetheless. Precise representation is up to the renderer, but most likely something like <span>, <div> or similar.

class flask_nav.elements.View(text, endpoint, **kwargs)

Application-internal link.

The endpoint, *args and **kwargs are passed on to url_for() to get the link.

  • text – The text for the link.
  • endpoint – The name of the view.
  • kwargs – Extra keyword arguments for url_for()

Return url for this item.

Returns:A string with a link.
ignore_query = True

Whether or not to consider query arguments (?foo=bar&baz=1) when determining whether or not a View is active. By default, query arguments are ignored.”“”

class flask_nav.renderers.Renderer

Base interface for navigation renderers.

Visiting a node should return a string or an object that converts to a string containing HTML.


Fallback rendering for objects.

If the current application is in debug-mode (flask.current_app.debug is True), an <!-- HTML comment --> will be rendered, indicating which class is missing a visitation function.

Outside of debug-mode, returns an empty string.

class flask_nav.renderers.SimpleRenderer(**kwargs)

A very basic HTML5 renderer.

Renders a navigational structure using <nav> and <ul> tags that can be styled using modern CSS.

Parameters:kwargs – Additional attributes to pass on to the root <nav>-tag.