Skip to main content

@foxglove/embed

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.

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
  • device - Device data source

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.

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.

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)