Docs Menu

Docs HomeAtlas Charts

Embedded Dashboard Options

On this page

  • Embedded Dashboard Options
  • Dashboard Configuration
  • getChart('<chartID>')
  • setAutoRefresh()
  • setMaxDataAge()
  • setTheme(theme: 'dark' | 'light')
  • Dashboard Configuration Example

The Embedding SDK psrovides 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
});

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.

Tip

See also:

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({ ... }).

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

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.

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.

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.

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

See also:

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);
←  Embedded Dashboard OptionsIframe Options →