Navigation

Embedded Chart Options

You can customize the appearance and behavior your embedded charts with a variety of options. Options are available to charts embedded with the Embedding SDK and embedded within iframes.

Note

To embed charts from your dashboards, you must configure embedding options on your data sources. For instructions, see Embed Charts in Your Web Application.

The Embedding SDK provides the Javascript createChart method for rendering a chart within a web page. You can use options to control the height and width of the chart, as well as the refresh interval and other aspects.

Example

The following example uses the createChart method with options.

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

The following options are available to createChart:

Option
Type
Description
Required?
baseUrl
string
Base URL of the chart.
yes
chartID
string
Unique identifier of the chart.
yes
height
number
Height of the chart. If no height is provided, it defaults to the height of its container. If a value is provided without units, it is assumed to be pixels (px).
no
width
number
Width of the chart. If no width is provided, it defaults to the width of its container. If a value is provided without units, it is assumed to be pixels (px).
no
filter
object
A filter to apply to the chart.
no
autoRefresh
boolean

Specifies whether the chart automatically refreshes. If omitted, charts do not automatically refresh.

Use this option with the maxDataAge option to configure how often the chart refreshes.

no
maxDataAge
number

Specifies the maximum age of data to load from the cache when loading or refreshing the chart. If omitted, MongoDB Charts renders the chart with data from the cache if the data is less than one hour old.

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

no
theme
string

A theme for the chart to use. Valid options are:

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

Defaults to light.

no
background
string

A background color to apply to your chart instead of the theme background. You can specify:

  • A color hex code
  • A CSS color name
  • transparent for a transparent background

If no background is provided, the background color defaults to the current theme:

  • #FFFFFF for the light theme, or
  • #21313C for the dark theme.
no
showAttribution
boolean
Specifies whether or not to display the MongoDB logo below the chart. Defaults to true.
no
getUserToken
object

Function that returns a base64-encoded JWT token. Charts validates this token to determine if an authenticated chart will be rendered.

If authenticated access is enabled, the authenticated chart view is rendered only if Charts can validate the token using the configured authentication providers.

If the token is invalid, MongoDB Charts renders the unauthenticated chart if you enabled unauthenticated access. Otherwise, the chart does not render.

Tip
See also:
no

After the chart is created, you can control the configuration of the chart by calling methods on the Chart instance returned by ChartsEmbedSDK.createChart({ ... }).

Example

The following code snippets set the theme of a Chart instance named chart to dark and it to refresh automatically every 30 seconds.

chart.setTheme("dark");
chart.setAutoRefresh(true);
chart.setMaxDataAge(30);
Method
Description
setAutoRefresh

Specifies whether the chart automatically refreshes. If omitted, charts do not automatically refresh.

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

setMaxDataAge

Specifies the maximum age of data to load from the cache when loading or refreshing the chart. If omitted, MongoDB Charts renders the chart with data from the cache if the data is less than one hour old.

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

setFilter(filter: object)

Applies a query filter to the embedded chart. This method expects an object that contains valid query operators. Any fields referenced in this filter must be added to the User Specified Filters list in the Embed Chart modal window. An empty document {} is equivalent to no filter.

See the Embedding Tutorials for more information about enabling embedding for a chart and allowing fields for filter use.

setTheme(theme: 'dark' | 'light')
Sets the current theme of the embedded chart. When setting the theme to dark, you need to ensure that your chart's background color has appropriate contrast so that the information remains visible.

The following table describes how MongoDB Charts loads data from the cache when loading or refreshing the chart based on the autoRefresh and maxDataAge values.

autoRefresh Value
maxDataAge Value
MongoDB Charts Behavior
omitted or false
omitted

The chart does not automatically refresh.

When you initially load or manually refresh the chart, MongoDB Charts renders the chart with data from the cache 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 chart using this data.

omitted or false
-1

The chart does not automatically refresh.

When you initially load or manually refresh the chart, MongoDB Charts renders the chart using data from the cache. Charts only queries the data source for the latest data if the cache has no data for the chart.

omitted or false
0

The chart does not automatically refresh.

When you initially load or manually refresh the chart, MongoDB Charts queries the data source for the latest data, and renders the chart using this data. Charts doesn't read data from the cache.

omitted or false
Number greater than 0

The chart does not automatically refresh.

When you initially load or manually refresh the chart, MongoDB Charts renders the chart with data from the cache if the data younger than the maxDataAge value, in seconds. If the data from the cache is older than the maxDataAge value, in seconds, Charts queries the data source for the latest data, refreshes the cache, and renders the chart using this data.

true
omitted

The chart automatically refreshes every hour.

When you initially load, manually refresh, or automatically refresh the chart, MongoDB Charts renders the chart with data from the cache 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 chart using this data.

true
Number greater than or equal to 10

The chart automatically refreshes at the maxDataAge interval you specify, in seconds.

When you initially load, manually refresh, or automatically refresh the chart, MongoDB Charts renders the chart with data from the cache if the data younger than the maxDataAge value, in seconds. If the data from the cache is older than the maxDataAge value, in seconds, Charts queries the data source for the latest data, refreshes the cache, and renders the chart using this data.

true
Number less than 10

The chart automatically refreshes at the minimum period of 10 seconds.

When you initially load, manually refresh, or automatically refresh the chart, MongoDB Charts renders the chart with data from the cache if the data younger than the minimum maxDataAge value of 10 seconds. If the data from the cache is older than 10 seconds, Charts queries the data source for the latest data, refreshes the cache, and renders the chart using this data.

Give Feedback