Panel settings API

Use the panel settings API to build a settings interface for your extension panels.

The panel settings API allows you to define configurable settings for your extension, and render them in a way that matches Foxglove Studio's appearance – all without having to write any custom UI code.

The PanelExtensionContext exposes methods for the business logic of your custom panel – including one to define your settings interface and to configure its values. Check out @foxglove/studio for full type descriptions on all possible configuration values.

updatePanelSettingsEditor

updatePanelSettingsEditor: (settings: Readonly<SettingsTree>) => void

Invoke the updatePanelSettingsEditor on your panel's PanelExtensionContext instance to define or update its settings.

const panelSettings: SettingsTree = {
  nodes: { ... },
  actionHandler: (action: SettingsTreeAction) { ... }
};

context.updatePanelSettingsEditor(panelSettings);

SettingsTree

The settings argument must be a valid SettingsTree and include two important properties – nodes and actionHandler:

• nodes - Hierarchical structure where each node can contain input fields, display fields, or even other nodes
• actionHandler - Function that is invoked when the user interacts with the settings UI; contains logic to process the interactions and update the panel or settings tree

The example tree below has a title text input field inside a General section along with an actionHandler to respond to updates for the title field.

const panelSettings: SettingsTree = {
  nodes: {
    general: {
      label: "General",
      fields: {
        title: {
          label: "Title",
          input: "string",
          // `panelTitle` refers to a value in your extension panel's config
          value: panelTitle,
        },
      },
    },
  },
  actionHandler: (action: SettingsTreeAction) {
    switch (action.action) {
      case "perform-node-action":
        // Handle user-defined actions for nodes in the settings tree
        break;
      case "update":
        if (action.payload.path[0] === "general" && action.payload.path[1] === "title") {
          // Read action.payload.value for the new panel title value
          panelTitle = action.payload.value;

          // Update your panel's state accordingly
        }
        break;
    }
  },
}

context.updatePanelSettingsEditor(panelSettings);

SettingsTreeAction

A SettingsTreeAction describes how the settings UI should update when a user interacts with its fields.

Each SettingsTreeAction has a payload with a path to the settings field to update (e.g. ["general", "title"]).

The update action corresponds to a user setting a new value for a field (e.g. "My new title").

Input types

In addition to the string input type in the example above, the panel API provides a wide array of types for your extension panel input fields.

Each input type has different properties that you can configure:

• autocomplete
• boolean
• rgb
• rgba
• gradient
• messagepath
• select
• string
• toggle
• vec3
• vec2