UI Components

New in NetBox v4.6

All UI components described here were introduced in NetBox v4.6. Be sure to set the minimum NetBox version to 4.6.0 for your plugin before incorporating any of these resources.

To simplify the process of designing your plugin's user interface, and to encourage a consistent look and feel throughout the entire application, NetBox provides a set of components that enable programmatic UI design. These make it possible to declare complex page layouts with little or no custom HTML.

Page Layout

A layout defines the general arrangement of content on a page into rows and columns. The layout is defined under the view and declares a set of rows, each of which may have one or more columns. Below is an example layout.

+-------+-------+-------+
| Col 1 | Col 2 | Col 3 |
+-------+-------+-------+
|         Col 4         |
+-----------+-----------+
|   Col 5   |   Col 6   |
+-----------+-----------+

The above layout can be achieved with the following declaration under a view:

from netbox.ui import layout
from netbox.views import generic

class MyView(generic.ObjectView):
    layout = layout.Layout(
        layout.Row(
            layout.Column(),
            layout.Column(),
            layout.Column(),
        ),
        layout.Row(
            layout.Column(),
        ),
        layout.Row(
            layout.Column(),
            layout.Column(),
        ),
    )

Note

Currently, layouts are supported only for subclasses of generic.ObjectView.

Layout

A collection of rows and columns comprising the layout of content within the user interface.

Parameters:

Name	Type	Description	Default
*rows		One or more Row instances	()

SimpleLayout

Bases: Layout

A layout with one row of two columns and a second row with one column.

Plugin content registered for left_page, right_page, or full_width_page is included automatically. Most object views in NetBox utilize this layout.

+-------+-------+
| Col 1 | Col 2 |
+-------+-------+
|     Col 3     |
+---------------+

Parameters:

Name	Type	Description	Default
left_panels		Panel instances to be rendered in the top lefthand column	None
right_panels		Panel instances to be rendered in the top righthand column	None
bottom_panels		Panel instances to be rendered in the bottom row	None

Row

A collection of columns arranged horizontally.

Parameters:

Name	Type	Description	Default
*columns		One or more Column instances	()

Column

A collection of panels arranged vertically.

Parameters:

Name	Type	Description	Default
*panels		One or more Panel instances	()
width		Bootstrap grid column width (1-12). If unset, the column will expand to fill available space.	None

Panels

Within each column, related blocks of content are arranged into panels. Each panel has a title and may have a set of associated actions, but the content within is otherwise arbitrary.

Plugins can define their own panels by inheriting from the base class netbox.ui.panels.Panel. Override the get_context() method to pass additional context to your custom panel template. An example is provided below.

from django.utils.translation import gettext_lazy as _
from netbox.ui.panels import Panel

class RecentChangesPanel(Panel):
    template_name = 'my_plugin/panels/recent_changes.html'
    title = _('Recent Changes')

    def get_context(self, context):
        return {
            **super().get_context(context),
            'changes': get_changes()[:10],
        }

    def should_render(self, context):
        return len(context['changes']) > 0

NetBox also includes a set of panels suited for specific uses, such as displaying object details or embedding a table of related objects. These are listed below.

Panel

A block of content rendered within an HTML template.

Panels are arranged within rows and columns, (generally) render as discrete "cards" within the user interface. Each panel has a title and may have one or more actions associated with it, which will be rendered as hyperlinks in the top right corner of the card.

Attributes:

Name	Type	Description
template_name	str	The name of the template used to render the panel

Parameters:

Name	Type	Description	Default
title	str	The human-friendly title of the panel	None
actions	list	An iterable of PanelActions to include in the panel header	None

get_context(context)

Return the context data to be used when rendering the panel.

Parameters:

Name	Type	Description	Default
context	dict	The template context	required

should_render(context)

Determines whether the panel should render on the page. (Default: True)

Parameters:

Name	Type	Description	Default
context	dict	The panel's prepared context (the return value of get_context())	required

render(context)

Render the panel as HTML.

Parameters:

Name	Type	Description	Default
context	dict	The template context	required

ObjectPanel

Bases: Panel

Base class for object-specific panels.

Parameters:

Name	Type	Description	Default
accessor	str	The dotted path in context data to the object being rendered (default: "object")	None

ObjectAttributesPanel

Bases: ObjectPanel

A panel which displays selected attributes of an object.

Attributes are added to the panel by declaring ObjectAttribute instances in the class body (similar to fields on a Django form). Attributes are displayed in the order they are declared.

Note that the only and exclude parameters are mutually exclusive.

Parameters:

Name	Type	Description	Default
only	list	If specified, only attributes in this list will be displayed	None
exclude	list	If specified, attributes in this list will be excluded from display	None

OrganizationalObjectPanel

Bases: ObjectAttributesPanel

An ObjectPanel with attributes common to OrganizationalModels. Includes name and description attributes.

NestedGroupObjectPanel

Bases: ObjectAttributesPanel

An ObjectPanel with attributes common to NestedGroupObjects. Includes the parent attribute.

CommentsPanel

Bases: ObjectPanel

A panel which displays comments associated with an object.

Parameters:

Name	Type	Description	Default
field_name	str	The name of the comment field on the object (default: "comments")	'comments'

JSONPanel

Bases: ObjectPanel

A panel which renders formatted JSON data from an object's JSONField.

Parameters:

Name	Type	Description	Default
field_name	str	The name of the JSON field on the object	required
copy_button	bool	Set to True (default) to include a copy-to-clipboard button	True

RelatedObjectsPanel

Bases: Panel

A panel which displays the types and counts of related objects.

ObjectsTablePanel

Bases: Panel

A panel which displays a table of objects (rendered via HTMX).

Parameters:

Name	Type	Description	Default
model	str	The dotted label of the model to be added (e.g. "dcim.site")	required
filters	dict	A dictionary of arbitrary URL parameters to append to the table's URL. If the value of a key is a callable, it will be passed the current template context.	None
include_columns	list	A list of column names to always display (overrides user preferences)	None
exclude_columns	list	A list of column names to hide from the table (overrides user preferences)	None

should_render(context)

Hide the panel if the user does not have view permission for the panel's model.

TemplatePanel

Bases: Panel

A panel which renders custom content using an HTML template.

Parameters:

Name	Type	Description	Default
template_name	str	The name of the template to render	required

TextCodePanel

Bases: ObjectPanel

A panel displaying a text field as a pre-formatted code block.

ContextTablePanel

Bases: ObjectPanel

A panel which renders a django-tables2/NetBoxTable instance provided via the view's extra context.

This is useful when you already have a fully constructed table (custom queryset, special columns, no list view) and just want to render it inside a declarative layout panel.

Parameters:

Name	Type	Description	Default
table	str | callable	Either the context key holding the table (e.g. "vlan_table") or a callable which accepts the template context and returns a table instance.	required

PluginContentPanel

Bases: Panel

A panel which displays embedded plugin content.

Parameters:

Name	Type	Description	Default
method	str	The name of the plugin method to render (e.g. "left_page")	required

Panel Actions

Each panel may have actions associated with it. These render as links or buttons within the panel header, opposite the panel's title. For example, a common use case is to include an "Add" action on a panel which displays a list of objects. Below is an example of this.

from django.utils.translation import gettext_lazy as _
from netbox.ui import actions, panels

panels.ObjectsTablePanel(
    model='dcim.Region',
    title=_('Child Regions'),
    filters={'parent_id': lambda ctx: ctx['object'].pk},
    actions=[
        actions.AddObject('dcim.Region', url_params={'parent': lambda ctx: ctx['object'].pk}),
    ],
),

PanelAction

A link (typically a button) within a panel to perform some associated action, such as adding an object.

Attributes:

Name	Type	Description
template_name	str	The name of the template to render

Parameters:

Name	Type	Description	Default
label	str	The human-friendly button text	required
permissions	list	An iterable of permissions required to display the action	None
button_class	str	Bootstrap CSS class for the button	'primary'
button_icon	str	Name of the button's MDI icon	None

get_context(context)

Return the template context used to render the action element.

Parameters:

Name	Type	Description	Default
context	dict	The template context	required

render(context)

Render the action as HTML.

Parameters:

Name	Type	Description	Default
context	dict	The template context	required

LinkAction

Bases: PanelAction

A hyperlink (typically a button) within a panel to perform some associated action, such as adding an object.

Parameters:

Name	Type	Description	Default
view_name	str	Name of the view to which the action will link	required
view_kwargs	dict	Additional keyword arguments to pass to reverse() when resolving the URL	None
url_params	dict	A dictionary of arbitrary URL parameters to append to the action's URL. If the value of a key is a callable, it will be passed the current template context.	None

get_url(context)

Resolve the URL for the action from its view name and kwargs. Append any additional URL parameters.

Parameters:

Name	Type	Description	Default
context	dict	The template context	required

AddObject

Bases: LinkAction

An action to add a new object.

Parameters:

Name	Type	Description	Default
model	str	The dotted label of the model to be added (e.g. "dcim.site")	required
url_params	dict	A dictionary of arbitrary URL parameters to append to the resolved URL	None

CopyContent

Bases: PanelAction

An action to copy the contents of a panel to the clipboard.

Parameters:

Name	Type	Description	Default
target_id	str	The ID of the target element containing the content to be copied	required

Object Attributes

The following classes are available to represent object attributes within an ObjectAttributesPanel. Additionally, plugins can subclass netbox.ui.attrs.ObjectAttribute to create custom classes.

Class	Description
netbox.ui.attrs.AddressAttr	A physical or mailing address.
netbox.ui.attrs.BooleanAttr	A boolean value
netbox.ui.attrs.ChoiceAttr	A selection from a set of choices
netbox.ui.attrs.ColorAttr	A color expressed in RGB
netbox.ui.attrs.DateTimeAttr	A date or datetime value
netbox.ui.attrs.GenericForeignKeyAttr	A related object via a generic foreign key
netbox.ui.attrs.GPSCoordinatesAttr	GPS coordinates (latitude and longitude)
netbox.ui.attrs.ImageAttr	An attached image (displays the image)
netbox.ui.attrs.NestedObjectAttr	A related nested object (includes ancestors)
netbox.ui.attrs.NumericAttr	An integer or float value
netbox.ui.attrs.RelatedObjectAttr	A related object
netbox.ui.attrs.RelatedObjectListAttr	A list of related objects
netbox.ui.attrs.TemplatedAttr	Renders an attribute using a custom template
netbox.ui.attrs.TextAttr	A string (text) value
netbox.ui.attrs.TimezoneAttr	A timezone with annotated offset
netbox.ui.attrs.UtilizationAttr	A numeric value expressed as a utilization graph

ObjectAttribute

Base class for representing an attribute of an object.

Attributes:

Name	Type	Description
template_name	str	The name of the template to render
placeholder	str	HTML to render for empty/null values

Parameters:

Name	Type	Description	Default
accessor	str	The dotted path to the attribute being rendered (e.g. "site.region.name")	required
label	str	Human-friendly label for the rendered attribute	None

get_value(obj)

Return the value of the attribute.

Parameters:

Name	Type	Description	Default
obj	object	The object for which the attribute is being rendered	required

get_context(obj, attr, value, context)

Return any additional template context used to render the attribute value.

Parameters:

Name	Type	Description	Default
obj	object	The object for which the attribute is being rendered	required
attr	str	The name of the attribute being rendered	required
value		The value of the attribute on the object	required
context	dict	The panel template context	required

AddressAttr

Bases: MapURLMixin, ObjectAttribute

A physical or mailing address.

Parameters:

Name	Type	Description	Default
map_url	bool / str	The URL to use when rendering the address. If True, the address will render as a hyperlink using settings.MAPS_URL.	True

BooleanAttr

Bases: ObjectAttribute

A boolean attribute.

Parameters:

Name	Type	Description	Default
display_false	bool	If False, a placeholder will be rendered instead of the "False" indication	True

ChoiceAttr

Bases: ObjectAttribute

A selection from a set of choices.

The class calls get_FOO_display() on the terminal object resolved by the accessor to retrieve the human-friendly choice label. For example, accessor="interface.type" will call interface.get_type_display(). If a get_FOO_color() method exists on that object, it will be used to render a background color for the attribute value.

ColorAttr

Bases: ObjectAttribute

An RGB color value.

DateTimeAttr

Bases: ObjectAttribute

A date or datetime attribute.

Parameters:

Name	Type	Description	Default
spec	str	Controls the rendering format. Use 'date' for date-only rendering, or 'seconds'/'minutes' for datetime rendering with the given precision.	'seconds'

GenericForeignKeyAttr

Bases: ObjectAttribute

An attribute representing a related generic relation object.

This attribute is similar to RelatedObjectAttr but uses the ContentType of the related object to be displayed alongside the value.

Parameters:

Name	Type	Description	Default
linkify	bool	If True, the rendered value will be hyperlinked to the related object's detail view	None

GPSCoordinatesAttr

Bases: MapURLMixin, ObjectAttribute

A GPS coordinates pair comprising latitude and longitude values.

Parameters:

Name	Type	Description	Default
latitude_attr	float	The name of the field containing the latitude value	'latitude'
longitude_attr	float	The name of the field containing the longitude value	'longitude'
map_url	bool	If true, the address will render as a hyperlink using settings.MAPS_URL	True

ImageAttr

Bases: ObjectAttribute

An attribute representing an image field on the model. Displays the uploaded image.

Parameters:

Name	Type	Description	Default
load_lazy	bool	If True, the image will be loaded lazily (default: True)	True
decoding	str	Image decoding option ('async', 'sync', 'auto', None)	None

NestedObjectAttr

Bases: ObjectAttribute

An attribute representing a related nested object. Similar to RelatedObjectAttr, but includes the ancestors of the related object in the rendered output.

Parameters:

Name	Type	Description	Default
linkify	bool	If True, the rendered value will be hyperlinked to the related object's detail view	None
max_depth	int	Maximum number of ancestors to display (default: all)	None
colored	bool	If True, render the object as a colored badge when it exposes a color attribute	False

NumericAttr

Bases: ObjectAttribute

An integer or float attribute.

Parameters:

Name	Type	Description	Default
unit_accessor	str	Accessor for the unit of measurement to display alongside the value (if any)	None
copy_button	bool	Set to True to include a copy-to-clipboard button	False

RelatedObjectAttr

Bases: ObjectAttribute

An attribute representing a related object.

Parameters:

Name	Type	Description	Default
linkify	bool	If True, the rendered value will be hyperlinked to the related object's detail view	None
grouped_by	str	A second-order object to annotate alongside the related object; for example, an attribute representing the dcim.Site model might specify grouped_by="region"	None
colored	bool	If True, render the object as a colored badge when it exposes a color attribute	False

RelatedObjectListAttr

Bases: RelatedObjectAttr

An attribute representing a list of related objects.

The accessor may resolve to a related manager or queryset.

Parameters:

Name	Type	Description	Default
max_items	int	Maximum number of items to display	None
overflow_indicator	str | None	Marker rendered as a final list item when additional objects exist beyond max_items; set to None to suppress it	'…'

TemplatedAttr

Bases: ObjectAttribute

Renders an attribute using a custom template.

Parameters:

Name	Type	Description	Default
template_name	str	The name of the template to render	required
context	dict	Additional context to pass to the template when rendering	None

TextAttr

Bases: ObjectAttribute

A text attribute.

Parameters:

Name	Type	Description	Default
style	str	CSS class to apply to the rendered attribute	None
format_string	str	If specified, the value will be formatted using this string when rendering	None
copy_button	bool	Set to True to include a copy-to-clipboard button	False

TimezoneAttr

Bases: ObjectAttribute

A timezone value. Includes the numeric offset from UTC.

UtilizationAttr

Bases: ObjectAttribute

Renders the value of an attribute as a utilization graph.