@foxglove/embed

Team

Enterprise

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.

Installation

npm

npm install --save @foxglove/embed

yarn

yarn add @foxglove/embed

Examples

Basic Usage

import { FoxgloveViewer } from "@foxglove/embed";

// Create a frame with a parent element
const viewer = new FoxgloveViewer({
  parent: document.getElementById("container")!,
  orgSlug: "my-org",
  initialDataSource: {
    type: "recording",
    recordingId: "rec_0dHVqSWhIQ8HUUJU",
    projectId: "prj_0dX15xqpCP0yPYNq",
  },
});

File Data Source

// Open a file picker and set the selected file as data source
window
  .showOpenFilePicker({
    multiple: false,
    types: [
      {
        description: ".bag, .db3, .ulg, .ulog, .mcap",
        accept: {
          "application/octet-stream": [".bag", ".db3", ".ulg", ".ulog", ".mcap"],
        },
      },
    ],
  })
  .then(async (handles) => {
    const file = await handles[0]!.getFile();
    viewer.setDataSource({
      type: "file",
      file,
    });
  });

Live Data Source

// Connect to a Foxglove WebSocket
viewer.setDataSource({
  type: "live",
  protocol: "foxglove-websocket",
  url: "ws://localhost:8765",
});

// Connect to a ROS Bridge
viewer.setDataSource({
  type: "live",
  protocol: "rosbridge-websocket",
  url: "ws://localhost:9090",
});

// Connect to a remote file
viewer.setDataSource({
  type: "live",
  protocol: "remote-file",
  url: "https://example.com/data.bag",
});

Recording Data Source

viewer.setDataSource({
  type: "recording",
  recordingId: "rec_0dHVqSWhIQ8HUUJU",
  projectId: "prj_0dX15xqpCP0yPYNq",
});

Layout Management

// Load a layout from a JSON file
window
  .showOpenFilePicker({
    multiple: false,
    types: [
      {
        description: ".json",
        accept: {
          "application/json": [".json"],
        },
      },
    ],
  })
  .then(async (handles) => {
    const file = await handles[0]!.getFile();
    const layoutData = JSON.parse(await file.text());
    viewer.setLayoutData(layoutData);
  });

Events

const onInit = (e: Event) => {
  console.warn(`FoxgloveViewer initialized`);
};

const onError = (e: CustomEvent<string>) => {
  console.warn(`FoxgloveViewer error: ${e.detail}`);
};

// Register event listeners
viewer.addEventListener("ready", onInit);
viewer.addEventListener("error", onError);

// Unregister event listeners
viewer.removeEventListener("ready", onInit);
viewer.removeEventListener("error", onError);

Overriding the default src

import { FoxgloveViewer } from "@foxglove/embed";

// Create a frame with a parent element
const viewer = new FoxgloveViewer({
  parent: document.getElementById("container")!,
  orgSlug: undefined,
  src: "http://localhost:8080/",
});

Extension Installation

warning

This functionality is not supported by all Foxglove versions and plans, so it may result in an error event.

// Install a local extension file
window
  .showOpenFilePicker({
    multiple: false,
    types: [
      {
        description: ".foxe",
        accept: {
          "application/zip": [".foxe"],
        },
      },
    ],
  })
  .then(async (handles) => {
    const file = await handles[0]!.getFile();
    viewer.installExtensions([file]);
  });

API Reference

FoxgloveViewer

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.
• initialLayout? - The initial 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.

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
• live - Live data source (WebSocket, ROS Bridge, Remote File)
• recording - Recording data source

setLayoutData(layout: LayoutData): void

Sets the layout of the Foxglove app.

Parameters:

• layout - The layout configuration object that defines the panel layout, workspace settings, and visualization state

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

warning

This functionality is not supported by all Foxglove versions and plans, so it may result in an error event.

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.

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 system color scheme is used.

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)

Error Handling

The FoxgloveViewer class validates inputs and throws descriptive errors for invalid configurations:

• Invalid src URLs
• Unsupported file types for live data sources
• Missing required parameters
• Invalid WebSocket URLs