Skip to main content

@foxglove/embed

Secure context required

Foxglove must run in a secure context. Serve your application over HTTPS or from localhost.

This package provides the FoxgloveViewer class. This class creates and manages an iframe to embed Foxglove in your application. It provides methods to set data sources, layouts, and install extensions programmatically.

FoxgloveViewer class​

The main class for managing a Foxglove iframe.

Constructor​

new FoxgloveViewer(options: FoxgloveViewerOptions)

Options:

  • parent - The parent element to append the iframe to. Required if iframe is not provided.
  • orgSlug - The Foxglove organization the user should be signed into. Passing this parameter is recommended so the user can be prompted to switch to the correct org if necessary.
  • src? - The URL where the Foxglove app is hosted. Defaults to https://embed.foxglove.dev/.
  • initialDataSource? - The initial data source to set when the frame is ready.
  • initialLayoutParams? - The initial selected layout to set when the frame is ready.
  • initialExtensions? - The initial extensions to install when the frame is ready.
  • colorScheme? - The color scheme the application should use.
  • keybindings? - Custom keybinding configuration for the embedded viewer. An array of Keybinding objects that override default shortcuts or register custom keybindings with handlers.

Methods​

setDataSource(dataSource: DataSource): void​

Sets the data source of the Foxglove app.

Parameters:

  • dataSource - The data source configuration

Supported data source types:

  • file - Local file data source
  • remote-file - Remote file data source
  • device - Device data source
  • recording - Recording data source
  • live - Live data source (WebSocket, ROS Bridge)

Example:

// Set a recording data source
viewer.setDataSource({
  type: "recording",
  projectId: "prj_abc123",
  recordingId: "rec_xyz789",
});

// Set a recording data source with autoplay
viewer.setDataSource({
  type: "recording",
  projectId: "prj_abc123",
  recordingId: "rec_xyz789",
  // Playback will start automatically when the data source is loaded
  autoplay: true,
});

selectLayout(params: SelectLayoutParams): void​

Load a layout from the local storage or create a new one and save it to the local storage if no layout with the same storage key is found or if the force parameter is true.

Parameters:

  • params - The parameters to select the layout
    • storageKey - The storage key to identify the layout in local storage. When reusing the same storage key, any modifications made by the user will be restored unless force is true.
    • opaqueLayout - The layout data to load if this layout did not already exist, or if force is true. This is an opaque JavaScript object, which should be parsed from a JSON layout file that was exported from the Foxglove app. If not provided, the default layout will be used.
    • force - If true, opaqueLayout will override the layout if it already exists. Default: false

getLayout(): Promise<OpaqueLayoutData>​

Retrieve the currently configured layout from the embedded viewer. Returns a Promise that resolves with an opaque JavaScript object representing the current layout. This can be used as the opaqueLayout property of SelectLayoutParams.

seekPlayback(time: Time | number): void​

Seek playback to the given absolute timestamp. The time is an absolute value (e.g. seconds since the UNIX epoch), not a relative offset or duration. Behaves as if the user clicked the playback bar to seek. If the viewer is not ready or the current data source doesn't support seeking, this is a no-op. Out-of-range values are clamped to the time range of the current data source.

Parameters:

  • time - An absolute Time object ({ sec: number; nsec: number }) or an absolute timestamp as a number of seconds (e.g. epoch seconds)

Example:

// Seek using seconds
viewer.seekPlayback(1742000000.5);

// Seek using a Time object
viewer.seekPlayback({ sec: 1742000000, nsec: 500000000 });

installExtensions(extensions: Array<string | File>): void​

warning

This functionality is only supported in the fully self-hosted embedded viewer. Please refer to the self-hosted documentation for more information.

warning

Since the self-hosted embedded viewer runs on your own infrastructure, you won't be able to access your organization's extensions hosted on Foxglove's servers.

Parameters:

  • extensions - The list of extensions as an array of URLs string pointing to a .foxe files and/or .foxe file handles

isReady(): boolean​

Returns whether the frame is ready to receive commands.

Returns: true if the frame is ready, false otherwise.

destroy(): void​

Destroys the frame. This removes the iframe from the DOM and stops listening for messages.

isDestroyed(): boolean​

Returns whether the frame has been destroyed.

Returns: true if the frame has been destroyed, false otherwise.

setKeybindings(keybindings: Keybinding[]): void​

Sets the custom keybinding configuration for this viewer instance. Each call fully replaces the previous configuration. The viewer checks custom keybindings before default ones. Calling with an empty array restores the viewer's default keybindings.

Parameters:

  • keybindings - An array of Keybinding objects. Each keybinding specifies a key (character key such as "p", physical code such as "KeyW", or named key such as "Escape"), optional modifiers, and either a command (built-in shortcut ID or "noop") or a handler function.

Example:

// Override a built-in shortcut and register a custom keybinding
viewer.setKeybindings([
  // Configure the "p" key to trigger the "toggle playback" command
  { key: "p", command: "player.togglePlayback" },
  // Suppress the default Space keybinding
  { key: " ", command: "noop" },
  // Register a custom keybinding
  {
    key: "t",
    modifiers: ["PrimaryModifier"],
    handler: () => {
      console.log("Custom keybinding triggered!");
    },
  },
]);

setColorScheme(colorScheme: "light" | "dark" | "auto"): void​

Change the color scheme used by the frame.

Parameters:

  • colorScheme - The color scheme to use. When set to "auto", the color scheme is inherited from the containing page.

addEventListener<K extends keyof EventMap>(type: K, listener: (ev: EventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;​

Registers an event listener.

Parameters:

  • type - The event type to listen for (ready or error)
  • listener - The event listener function to call when the event occurs
  • options? - Optional event listener options (capture, once, passive, signal)

removeEventListener<K extends keyof EventMap>(type: K, listener: (ev: EventMap[K]) => void, options?: boolean | EventListenerOptions): void;​

Removes an event listener.

Parameters:

  • type - The event type to remove the listener from (ready or error)
  • listener - The event listener function to remove
  • options? - Optional event listener options (capture)