For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
MongoDB Branding Shape
Click here >
Docs Menu
Docs Home
/ /
Options
Docs Home
/ /
Embed a Dashboard
/
Options
Docs Home
/
Development
/
Charts
/
Embedding
/
Embed a Dashboard
/
Options

Embedded Dashboard SDK Methods and Options

The Embedding SDK provides the JavaScript createDashboard() method for rendering a dashboard within a web page. You can use options to control many aspects of a dashboard (for example, its height and width).

Example

The following example demonstrates how to use the createDashboard method with options that specify the height and width of the dashboard.

const dashboard = sdk.createDashboard({
  dashboardId: "8d4dff93-e7ca-4ccd-a622-e20e8a100197",
  baseUrl: "https://charts.mongodb.com/dashboards-embedding-examples-hmewt",
  height: 300,
  width: 400
});

Embedded Dashboard createDashboard() Options

The createDashboard() method takes the following options:

Option
Type
Description
Required?

autoRefresh

boolean

Flag that specifies whether the dashboard automatically refreshes. If omitted, dashboards don't automatically refresh.

Use this option with the maxDataAge option to configure automatic dashboard refresh frequency.

no

background

string

Background color to apply to your dashboard instead of the theme background. You can specify:

  • A color hex code

  • A CSS color name

  • A transparent background using the value transparent

If omitted, the background color defaults to the current theme:

  • #F1F5F4 for the light theme, or

  • #12212C for the dark theme.

no

baseUrl

string

Base URL of the dashboard.

yes

dashboardId

string

Unique string that identifies the dashboard.

yes

getUserToken

object

Function that returns a base64-encoded JWT token. Charts validates this token to determine whether to render an authenticated dashboard.

If you enabled authenticated access, Atlas Charts renders the authenticated dashboard view only if Charts can validate the token using the configured authentication providers. If the token is invalid, Charts doesn't render the dashboard.

If you enabled unauthenticated access, Atlas Charts always renders the unauthenticated dashboard view. To learn more, see Embed an Authenticated Chart using a Custom JWT Provider.

no

height

number

Height of the dashboard. If omitted, it defaults to the height of its container. If you provide a value without units, it defaults to pixels (px).

no

maxDataAge

number

Maximum age of data to load from the cache when loading or refreshing the dashbnoard. If omitted, Atlas Charts renders the dashboard with data from the cache only if the data is less than one hour old.

If the data from the cache is more than one hour old, Charts queries the data source for the latest data, refreshes the cache, and renders the dashboard using this data.

To learn how Atlas Charts loads data from the cache when loading or refreshing the dashboard based on the autoRefresh and maxDataAge values, see Refresh and Data Caching Behavior.

no

showAttribution

boolean

Specifies whether to display the MongoDB logo below the dashboard. Defaults to true.

no

theme

string

Theme to use on the dashboard. The following options are valid:

  • light for a light background with dark text and dashboard elements, or

  • dark for a dark background with light text and dashboard elements.

If omitted, it defaults to light.

no

width

number

Width of the dashboard. If omitted, it defaults to the width of its container. If you specify a value without units, it defaults to pixels (px).

no

After the dashboard is created, you can control the configuration of the dashboard by calling methods on the Dashboard instance returned by DashboardsEmbedSDK.createDashboard({ ... }).

Dashboard Configuration Methods

After you create a dashboard, you can control the configuration of the dashboard by calling methods on the Dashboard instance returned by DashboardsEmbedSDK.createDashboard({ ... }).

getChart('<chartID>')

Retrieves a specific chart from the embedded dashboard using the chart's chartId string. After calling this method, you can highlight elements or filter data on the chart.

setAutoRefresh()

Flag that specifies whether the dashboard refreshes automatically. If omitted, dashboards don't refresh automatically.

Use this method with the setMaxDataAge method to configure how often the dashboard refreshes.

setMaxDataAge()

Maximum age of data to load from the cache when loading or refreshing the dashboard. If omitted, Atlas Charts renders the dashboard with data from the cache only if the data is less than one hour old.

If the data from the cache is more than one hour old, Charts queries the data source for the latest data, refreshes the cache, and renders the dashboard using this data.

To learn how Atlas Charts loads data from the cache when loading or refreshing the dashboard based on the setAutoRefresh and setMaxDataAge values, see Refresh and Data Caching Behavior.

setTheme(theme: 'dark' | 'light')

Current theme of the embedded dashboard. When setting the theme to dark, ensure that your dashboard's background color has appropriate contrast so that the information is visible.

Tip

Dashboard Configuration Example

The example code snippets configures the following options for a Dashboard instance named dashboard:

  • The theme to dark

  • The automatic refresh rate to every 60 seconds

dashboard.setTheme("dark");
dashboard.setAutoRefresh(true);
dashboard.setMaxDataAge(60);

Back

Options

Next

Configure Iframe Style and Theme

On this page