UI Components

New in NetBox v4.5

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

Beta Feature

UI components are considered a beta feature, and are still under active development. Please be aware that the API for resources on this page is subject to change in future releases.

To simply 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_path is included automatically. Most object views in NetBox utilize this layout.

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

Parameters:

Name	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	`()`

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],
        }

NetBox also includes a set of panels suite for specific uses, such as display 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

`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`

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.ColorAttr`	A color expressed in RGB
`netbox.ui.attrs.ChoiceAttr`	A selection from a set of choices
`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
`netbox.ui.attrs.NumericAttr`	An integer or float value
`netbox.ui.attrs.RelatedObjectAttr`	A related object
`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

`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`

`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

`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