diff --git a/docs/customization/custom-scripts.md b/docs/customization/custom-scripts.md
index 2e0e983c9..bdc3f9104 100644
--- a/docs/customization/custom-scripts.md
+++ b/docs/customization/custom-scripts.md
@@ -304,7 +304,7 @@ A particular object within NetBox. Each ObjectVar must specify a particular mode
* `model` - The model class
* `query_params` - A dictionary of query parameters to use when retrieving available options (optional)
-* `context` - A custom dictionary mapping template context variables to fields, used when rendering `` elements within the dropdown menu (optional)
+* `context` - A custom dictionary mapping template context variables to fields, used when rendering ` ` elements within the dropdown menu (optional; see below)
* `null_option` - A label representing a "null" or empty choice (optional)
To limit the selections available within the list, additional query parameters can be passed as the `query_params` dictionary. For example, to show only devices with an "active" status:
@@ -332,6 +332,22 @@ site = ObjectVar(
)
```
+#### Context Variables
+
+Custom context variables can be passed to override the default attribute names or to display additional information, such as a parent object.
+
+| Name | Default | Description |
+|---------------|-----------------|------------------------------------------------------------------------------|
+| `value` | `"id"` | The attribute which contains the option's value |
+| `label` | `"display"` | The attribute used as the option's human-friendly label |
+| `description` | `"description"` | The attribute to use as a description |
+| `depth`[^1] | `"_depth"` | The attribute which indicates an object's depth within a recursive hierarchy |
+| `disabled` | -- | The attribute which, if true, signifies that the option should be disabled |
+| `parent` | -- | The attribute which represents the object's parent object |
+| `count`[^1] | -- | The attribute which contains a numeric count of related objects |
+
+[^1]: The value of this attribute must be a positive integer
+
### MultiObjectVar
Similar to `ObjectVar`, but allows for the selection of multiple objects.
diff --git a/netbox/utilities/forms/fields/dynamic.py b/netbox/utilities/forms/fields/dynamic.py
index 3cd956694..cb24ea08d 100644
--- a/netbox/utilities/forms/fields/dynamic.py
+++ b/netbox/utilities/forms/fields/dynamic.py
@@ -64,8 +64,18 @@ class DynamicModelChoiceMixin:
null_option: The string used to represent a null selection (if any)
disabled_indicator: The name of the field which, if populated, will disable selection of the
choice (DEPRECATED: pass `context={'disabled': '$fieldname'}` instead)
- context: A mapping of template variables to their API data keys (optional)
+ context: A mapping of template variables to their API data keys (optional; see below)
selector: Include an advanced object selection widget to assist the user in identifying the desired object
+
+ Context keys:
+ value: The name of the attribute which contains the option's value (default: 'id')
+ label: The name of the attribute used as the option's human-friendly label (default: 'display')
+ description: The name of the attribute to use as a description (default: 'description')
+ depth: The name of the attribute which indicates an object's depth within a recursive hierarchy; must be a
+ positive integer (default: '_depth')
+ disabled: The name of the attribute which, if true, signifies that the option should be disabled
+ parent: The name of the attribute which represents the object's parent object (e.g. device for an interface)
+ count: The name of the attribute which contains a numeric count of related objects
"""
filter = django_filters.ModelChoiceFilter
widget = widgets.APISelect