netbox/docs/plugins/development/user-interface.md

User Interface

Light & Dark Mode

The NetBox user interface supports toggling between light and dark versions of the theme. If needed, a plugin can determine the currently active color theme by inspecting window.localStorage['netbox-color-mode'], which will indicate either light or dark.

Additionally, when the color scheme is toggled by the user, a custom event netbox.colorModeChanged indicating the new scheme is dispatched. A plugin can listen for this event if needed to react to the change:

window.addEventListener('netbox.colorModeChanged', e => {
  const customEvent = e as CustomEvent<ColorModeData>;
  console.log('New color mode:', customEvent.detail.netboxColorMode);
});

User Preferences

Plugins can register their own user preferences, which are displayed in a dedicated "Plugins" section of each user's preferences page. To do so, create a file named preferences.py in your plugin and define a dictionary named preferences mapping each preference name to a UserPreference instance.

from django.utils.translation import gettext_lazy as _
from users.preferences import UserPreference

preferences = {
    'default_view': UserPreference(
        label=_('Default view'),
        choices=(
            ('summary', _('Summary')),
            ('detail', _('Detail')),
        ),
        description=_('The default view for plugin objects'),
    ),
}

!!! tip

The path to the preferences dictionary can be modified by setting `user_preferences` in the PluginConfig instance.

A UserPreference accepts the following arguments:

Argument	Required	Description
label	Yes	The human-friendly name of the preference
choices	Yes	An iterable of (value, label) two-tuples
default	-	The default value for the preference
description	-	A brief description of the preference
coerce	-	A callable to convert the submitted value to the appropriate type (e.g. int)
warning	-	A warning message to display alongside the preference

Each preference is stored under the path plugins.<plugin_name>.<preference_name>, where <plugin_name> is the last component of the plugin's PluginConfig.name (e.g. netbox_foo for a plugin named acme.netbox_foo). Its value for the current user can be retrieved by calling get() on the user's config.