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	Description	Default
`*rows`	One or more Row instances	`()`
`breadcrumbs`	An ordered iterable of `Breadcrumb` instances rendered at the top of the page, after the default breadcrumb linking to the object's list view. The trail defined on a model's base view is shared across all of that model's object views (e.g. its detail view and every peer/tabbed view).	`None`
`root_breadcrumb`	Whether to prepend the default root breadcrumb (a link to the object's list view) to the trail. Set False for views whose list view is not an appropriate root (e.g. a user's personal token list), allowing the layout's own breadcrumbs to stand in its place.	`True`

`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	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`
`breadcrumbs`	Breadcrumb instances rendered at the top of the page (see Layout)	`None`
`root_breadcrumb`	Whether to prepend the default root breadcrumb (see Layout)	`True`

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

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

Attributes:

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

Parameters:

Name	Description	Default
`accessor`	The dotted path to the related object on the viewed instance (e.g. "site" or "device.rack"), or a callable which accepts the instance and returns the related object. If the resolved value is an iterable of objects, a breadcrumb is rendered for each (e.g. to represent a hierarchy of ancestors). Omit this (and pass `label`) to render a single breadcrumb describing the viewed object itself.	`None`
`label`	A label for the breadcrumb. Required when `accessor` is omitted. May be a string, or a callable which accepts the relevant object (the resolved related object when an accessor is given, otherwise the viewed instance) and returns the label. When an accessor is given and no label is set, the resolved object's string representation is used.	`None`
`url`	An optional URL for the breadcrumb's link. May be a string, or a callable which accepts the relevant object and returns a URL. When an accessor is given and no url is set, the resolved object's `get_absolute_url()` is used where available; an accessor-less breadcrumb is left unlinked instead.	`None`

`resolve(instance)`

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

`get_label(obj)`

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

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

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.ArrayAttr`	An array of values, shown as a comma-separated list
`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`

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

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`
`nested`	`bool`	If True and the related object exposes a callable `get_ancestors(include_self=True)`, render the object together with its ancestors as a breadcrumb, similar to `NestedObjectAttr`. Non-hierarchical objects continue to render normally.	`False`
`max_depth`	`int`	Maximum number of ancestors to display when `nested` is enabled. Ignored otherwise.	`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.