Plugins
Plugins are custom code you can write for Navigator. They are written for a particular location, for example a side bar panel, a tool in the cursor bar, or a tab in the selected Entity panel.
Plugins are written in Javascript with an optional HTML file as well.
You can create Plugins, upload their code and enable them on a Project View through the Plugins menu in Navigator. Plugins can also be managed in Operator. This article covers the shape of a Plugin, where it can run and what it is handed. You can read about writing, testing and uploading one in Plugins: Development.
File layout
A Plugin is a ZIP with an index.js file at its root, and an optional index.html file beside it.
The HTML file, if present, is added to the Plugin's element when it loads. It is removed with the element when the Plugin is disposed.
Any other file in the ZIP is served from ui.plugin/{pluginId}/file/{fileName}, so a Plugin can ship images, data or libraries of its own and fetch them at runtime. The UI toolkit is loaded this way.
Here is an example of a Plugin's index.js file.
Here is an example of a Plugin's index.html file. Please note the usage of an HTML ID for the styles and root element. It is highly recommended to work with a very unique ID to avoid conflicts with other Plugins and Navigator itself. The UI toolkit generates its class names per Plugin, so a Plugin built with it does not need this.
Plugin Locations
A Plugin's location decides where it can be loaded, what container it gets, and which params it is handed.
| Location | Description | |
|---|---|---|
Cursor barNAVIGATOR_CURSOR_BAR | The cursor bar is the toolbar found in the top-left corner of Navigator. It is responsible for actions the user performs when clicking on the scene or Entities in the scene. The Plugin loads when the user picks the tool and is disposed when they pick another, so a cursor Plugin needs no state of its own to know whether it is active. Its element sits over the viewer rather than in a panel. | ![]() |
Info ViewNAVIGATOR_INFO_VIEW | The Info View panel is the dialog that appears when an Entity is selected. This location replaces that panel's contents, so the Plugin is responsible for presenting the Entity itself. It is chosen by a Project View's selection settings rather than by enabling it: a selection action of "PLUGIN" with the Plugin's ID in "actionParams". You can read about selection settings in Project Views. | ![]() |
Selected Entity panel tabNAVIGATOR_INFO_VIEW_ENTITY | Adds a tab alongside Navigator's own tabs in the selected Entity panel, rather than replacing it. This is usually what you want: the user keeps the built-in views and gains yours. | |
Selected Multi-Entity panel tabNAVIGATOR_INFO_VIEW_MULTI_ENTITY | The same, for when several Entities are selected at once. | |
SidebarNAVIGATOR_SIDE_BAR | The side bar is the toolbar found in the left side of Navigator which holds Menu Items, Bookmarks, and Scene Tree. The Plugin gets a panel of its own. Set the Plugin setting "panelWidth" to control the panel's width. See Side panel width below. The Plugin is reloaded when the Project View changes. | |
BackgroundNAVIGATOR_BACKGROUND | Plugins that are set to load in the background will load automatically when the page loads without the user needing to click any buttons. Its element sits over the viewer. A background Plugin loads once the first Bookmark has loaded, and is reloaded when the Project View or the active Bookmark changes. | |
AI ToolAI_TOOL | Not a piece of UI. The Plugin is offered to the AI agent as a callable tool and exports Invoke rather than Run. You can read about it in Plugins: AI Tools. | |
OperatorOPERATOR | Loads inside the Operator management portal rather than Navigator. See Operator Plugins below, since its params are not Navigator's. |
A Plugin can also run inside a Custom Form, as a form component of "PLUGIN" with the Plugin's ID in its "pluginId" param and an optional "height", which is 250 pixels by default. You can read about Custom Forms in Custom Forms.
Enabling a Plugin
Setting a location is not enough on its own. Every Plugin must have "Enabled" set on its record, and most must also be enabled on the Project View being viewed:
- Cursor bar, Sidebar, Background and both selected Entity panel tabs must be enabled on the Project View. Navigator's Plugins menu does this, and it is stored in the view's "plugins.enabledIds" setting.
- Info View and Custom Form Plugins are chosen by the Project View's selection settings and by the form, so they are not enabled on the view.
- AI Tools are available across the account as soon as they are enabled.
A Plugin that appears to do nothing is almost always a Plugin that was never enabled on the view.
Plugin Params
Below are the parameters every Navigator location passes into the Plugin's Run function.
Params by location
Not every location is handed every param. The params above are present everywhere in Navigator. The ones below depend on where the Plugin runs, so check for a param rather than assuming it.
| Param | Where | What it is |
|---|---|---|
view | Every location except the cursor bar | The active Project View record. |
getCursor, setCursor, cursorIds | Every location except the cursor bar | Reads and sets the active cursor tool. "cursorIds" holds the tool IDs, so a Plugin can call setCursor([cursorIds.Pan]) while it asks the user to click a position, without the click selecting an Entity. |
setPanelWidth | Sidebar | Changes the panel width at runtime, taking the same value as the panelWidth setting. Affects the current session only. |
setFocusedAttachment | Info View, selected Entity panel tab, Custom Form | Opens Navigator's own attachment viewer on an attachment, with its siblings, so a Plugin does not need to build media browsing itself. Called as setFocusedAttachment(attachment, siblings). |
viewId, bookmark, bookmarkId, enableBookmark | Background | The active Project View's ID, the active Bookmark, its ID, and a call to activate a Bookmark. |
d3 | Custom Form | The d3 library, for drawing charts inside the form. |
What close does also depends on the location:
| Location | close() |
|---|---|
| Cursor bar | Switches back to the select tool, which disposes the Plugin. |
| Sidebar | Closes the panel. |
| Background | Disposes this Plugin until it is next reloaded. |
| Info View, both selected Entity panel tabs, Custom Form | Deselects everything, which closes the panel. |
The Plugin record
Every Plugin is handed its own record as params.plugin. It is worth knowing what is on it, because several fields exist specifically so a Plugin does not have to be edited per account or per deployment.
| Field | What it does |
|---|---|
Settings | Arbitrary JSON, passed to the Plugin when it loads. This is where an Entity Type ID, an endpoint, a threshold or a colour belongs, so one Plugin serves every account with no code change. Also carries the reserved panelWidth, and tool for AI Tools. |
Enabled | Turns a Plugin off without unpicking it from every Project View that references it. |
Group | An arbitrary grouping you can query against, so a whole related set can be retrieved and enabled at once. This is how an embedded Navigator can be told to enable a group of Plugins by URL param, and have that set change without the URL changing. |
Version | Increased every time a new code bundle is uploaded, and used as the cache key for the Plugin's code. You can read about caching in Plugins: Development. |
Icon, IconSource | The button icon, either a Font Awesome class (FONT_AWESOME) or a Client File ID (CLIENT_FILE) for your own image. For background Plugins the icon is only for identification in admin panels. |
IsLoginRequired | Requires a logged-in user. The Plugin's files are then fetched with the user's session rather than through the CDN. |
IsAccessRestricted | Restricts the Plugin to users granted access to it, either through the UIPlugin_<pluginId> permission or a User Group grant set in Operator. The API refuses the Plugin's code to anyone else, and Navigator shows them a message that they do not have access. |
We recommend leaving both of these off. Users usually control access through Project View access control and Entity Type access control, and a Plugin runs with the user's own permissions, so it can only show what that user can already see. Restrictions on the Plugin itself add a second set of rules to keep in step with those. Turn them on only when the Plugin itself must be hidden from some users. You can read about Project View access in Project Views.
Side panel width
A side bar Plugin's panel is 300px wide by default. The panelWidth setting takes either a fixed CSS width or a range, and a range is what makes the panel user-resizable.
A single value is a fixed width. Two values are a minimum and a maximum, which the user can drag between. Three values add the width to open at. A Plugin can also change this while it runs through the setPanelWidth param, which affects the current session only and does not rewrite the setting.
On a phone the side panel opens as a sheet across the bottom of the screen and takes the full width, so "panelWidth" does not apply there. Lay the panel out to fit whatever width it is given.
Operator Plugins
An Operator Plugin is handed a smaller set of params. There is no viewer, register or Menu Item manager, and none of the Navigator calls such as "close" and "select".
Worked examples
The FAQ pages in this section answer the cases most Plugins start from: making API requests, letting the user pick a position in the scene, and rendering directly to the Cesium viewer. The AI Tools page covers the agent-callable location, which uses a different entry point entirely.
You can read about writing, testing and uploading a Plugin in Plugins: Development, and about building its panel in Plugins: UI toolkit.

