UI Components

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(),
        ),
    )

Layout

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

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

Row

A collection of columns arranged horizontally.

Column

A collection of panels arranged vertically.

Breadcrumbs

Breadcrumbs are rendered at the top of an object's page to convey its position within a hierarchy and to provide quick navigation to related objects. By default, a single breadcrumb linking to the object's list view is shown. To add object-specific breadcrumbs, pass a list of Breadcrumb instances to your layout, just as you would its panels.

A Breadcrumb typically references an accessor (rather than a static value), which is resolved against the object being viewed when the page is rendered. The accessor may be a dotted attribute path or a callable. (A breadcrumb may instead define a static label; see below.)

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

class MyView(generic.ObjectView):
    layout = layout.SimpleLayout(
        breadcrumbs=[
            Breadcrumb('site'),
            Breadcrumb('location'),
            Breadcrumb('rack'),
        ],
        left_panels=[...],
        right_panels=[...],
    )

Each breadcrumb renders as a label (the string representation of the resolved object) and an optional link. If no explicit url is provided, the object's get_absolute_url() is used when available. A breadcrumb whose accessor resolves to None (or an empty iterable) renders as an empty string and is omitted, which simplifies conditional breadcrumbs (e.g. where a device may or may not be assigned to a rack).

To link a breadcrumb somewhere other than the related object's own page (for example, to a filtered list view), pass a url. A callable url receives the resolved object:

from django.urls import reverse

Breadcrumb('rir', url=lambda rir: f"{reverse('ipam:asn_list')}?rir_id={rir.pk}")

A callable accessor which returns an iterable renders one breadcrumb per object, which is useful for representing a hierarchy of ancestors:

Breadcrumb(lambda obj: obj.get_ancestors())

To render a breadcrumb that isn't tied to a related object, omit the accessor and pass a label. This is useful for linking to a parent view that isn't reachable via an attribute on the object (e.g. a user's personal token list):

from django.urls import reverse_lazy

Breadcrumb(label=_('My API Tokens'), url=reverse_lazy('account:usertoken_list'))

The label may also be a callable, which receives the relevant object (the resolved related object when an accessor is given, otherwise the viewed instance). This is useful for an unlinked descriptive crumb derived from the object:

Breadcrumb(label=lambda obj: f"{_('Units')} {obj.unit_list}")

The default root breadcrumb (linking to the object's list view) is prepended to the trail automatically. Where that list view isn't an appropriate root—for example, the global token list is admin-only, so a user's personal token page links to their own token list instead—pass root_breadcrumb=False to the layout and supply a replacement as the first breadcrumb:

SimpleLayout(
    root_breadcrumb=False,
    breadcrumbs=[
        Breadcrumb(label=_('My API Tokens'), url=reverse_lazy('account:usertoken_list')),
    ],
    ...
)

Breadcrumb

A navigation breadcrumb rendered at the top of an object view. Rather than wrapping a static value, a breadcrumb typically references an attribute on the object being viewed. This allows breadcrumbs to be declared once on a layout (alongside its panels) and rendered dynamically for each object. A breadcrumb whose resolved value is empty renders as an empty string and is omitted, which simplifies conditional breadcrumbs (e.g. where a device may or may not be assigned to a rack). A breadcrumb may instead define a static label, omitting the accessor entirely. This renders a single breadcrumb describing the viewed object directly (or a fixed destination) rather than a related object, which is useful for linking to a parent view that isn't a related object (e.g. a user's personal token list) or for an unlinked descriptive crumb (e.g. "Units 1-5" on a rack reservation).

resolve(instance)

Resolve the breadcrumb's accessor against the viewed instance and return the related object(s).

Parameters:

get_label(obj)

Return the breadcrumb's label for the given object, falling back to its string representation.

Parameters:

get_url(obj, fallback=True)

Return the URL to link the given object to, or None for an unlinked breadcrumb. When fallback is True, an object's get_absolute_url() is used in the absence of an explicit url.

Parameters:

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.

get_context(context)

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

Parameters:

should_render(context)

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

Parameters:

render(context)

Render the panel as HTML.

Parameters:

ObjectPanel

Bases: Panel

Base class for object-specific panels.

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.

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.

JSONPanel

Bases: ObjectPanel

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

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).

should_render(context)

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

Parameters:

TemplatePanel

Bases: Panel

A panel which renders custom content using an HTML template.

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.

PluginContentPanel

Bases: Panel

A panel which displays embedded plugin content.

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.

get_context(context)

Return the template context used to render the action element.

Parameters:

render(context)

Render the action as HTML.

Parameters:

LinkAction

Bases: PanelAction

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

get_url(context)

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

Parameters:

AddObject

Bases: LinkAction

An action to add a new object.

CopyContent

Bases: PanelAction

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

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.

ObjectAttribute

Base class for representing an attribute of an object.

get_value(obj)

Return the value of the attribute.

Parameters:

get_context(obj, attr, value, context)

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

Parameters:

AddressAttr

Bases: MapURLMixin, ObjectAttribute

A physical or mailing address.

ArrayAttr

Bases: TextAttr

An attribute comprising an array of values, rendered as a comma-separated list. If specified, format_string is applied to each item individually. Null and empty arrays are treated as equivalent: both render as the placeholder.

BooleanAttr

Bases: ObjectAttribute

A boolean attribute.

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.

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.

GPSCoordinatesAttr

Bases: MapURLMixin, ObjectAttribute

A GPS coordinates pair comprising latitude and longitude values.

ImageAttr

Bases: ObjectAttribute

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

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.

NumericAttr

Bases: ObjectAttribute

An integer or float attribute.

RelatedObjectAttr

Bases: ObjectAttribute

An attribute representing a related object.

RelatedObjectListAttr

Bases: RelatedObjectAttr

An attribute representing a list of related objects. The accessor may resolve to a related manager or queryset.

TemplatedAttr

Bases: ObjectAttribute

Renders an attribute using a custom template.

TextAttr

Bases: ObjectAttribute

A text attribute.

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.