Navigation

Embedded Chart Options

You can customize the appearance and behavior your embedded charts with a variety of options. Options are available to charts 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.

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.

You can set chart options within an iframe by adding inline style tags and by adding query parameters to the chart URL. Inline style tags allow you to specify display options such as height, width, background color, and border width. Query parameters allow you to specify a refresh interval for your chart, as well as a light or dark display theme.

Configure Auto Refresh and Data Caching Behavior

Use the autoRefresh query parameter to configure the chart to refresh automatically.

Use the maxDataAge query parameter to:

  • Determine the interval at which the chart refreshes if autoRefresh is true.

  • Configure the maximum age of data to load from the cache when loading or manually refreshing the chart if autoRefresh is false or omitted.

    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.

Use the options on the Unauthenticated tab on the Embed Chart dialog to customize the autoRefresh value in the iframe snippet.

Example

The following iframe embeds a chart which automatically refreshes every 30 seconds as defined by the autoRefresh=true and the maxDataAge=30 query parameters:

<iframe style="border: none;border-radius: 2px;box-shadow: 0 2px
10px 0 rgba(70, 76, 79, .2);" width="640" height="480" src="
{charts-host}/embed/charts?id=b3ca720f-4b4a-40b4-a726-e7dc0c49aa1c&
autoRefresh=true&maxDataAge=30"></iframe>

Considerations

  • The minimum cache duration is 10 seconds. If autoRefresh is true and you specify a maxDataAge value less than 10, the chart refreshes every 10 seconds.

  • If you specify an maxDataAge value which is not an integer or less than -1, an error is returned.

  • If your data source requires a Verified Signature, the signature validity (including the expiry date) is checked on each refresh. If the signature’s expiry date passed, the host web page must regenerate a new signature to continue rendering charts. For code examples using verified signatures, see MongoDB Charts Embedding Examples on GitHub.

    Example

    If autoRefresh is true, the cache duration is one minute (maxDataAge=60), and the expiry date of the signature is in one hour, the chart refreshes every minute for an hour. Once one hour has elapsed, the chart will not render and an error will be displayed as the signature is no longer valid. The host web page must regenerate a new signature to resume rendering the chart.

Specify a Display Theme

Use the theme query parameter to select a display theme:

  • light: chart axes and text are optimized for presentation against a light or white background.
  • dark: chart axes and text are optimized for presentation against a dark or black background.

Choosing a theme value only updates the iframe snippet you use to embed the chart in your application. The chart is not saved with a theme value. The chart renders with the light theme by default. Embedded charts that do not include the theme parameter also render with the light theme.

Note

Choosing the light or dark theme does not change the color palette that chart data elements use. All bars and marks display using the default palette or the custom palette the chart author chose.

For example, if you choose a chart bar to render in black, choosing the dark theme does not change the color of this bar to make it more visible against a dark background.

Customize Display Options

MongoDB Charts adds inline style properties to the iframe snippet you copy from the UI that add a background color and a border with a box shadow to the embedded chart based on the theme you selected:

  • light theme background: #FFFFFF
  • dark theme background: #21313C
  • border: none
  • border-radius: 2px
  • box-shadow: 0 2px 10px 0 rgba(70, 76, 79, .2)
  • width: 640
  • height: 480

Change the values of the inline style properties to change how the embedded chart displays in your application.

Background Color

  • Change the value of the background property to any value supported by the background CSS property to display the chart against it. See background in the MDN Web Docs for more information.
  • Change the background property to transparent to display the chart with a transparent background, allowing your application’s background to display through the chart.
  • Remove the background property to use the default background color of the theme you choose:
    • #FFFFFF for the light theme (default), or
    • #21313C for the dark theme.

Chart Border

  • Modify or remove the following properties to customize or remove the chart border:
    • border
    • border-radius
    • box-shadow

Display Theme

  • You can change the value of the theme query parameter in the iframe snippet after you paste it into your application. If you do, make sure you adjust the iframe’s inline style properties to match the theme you choose.

    Example

    If you change the theme from light to dark, adjust the value of the background property in the iframe snippet to display the chart against a dark background.

    Chart using light theme with default light theme background of #FFFFFF:

    Chart displayed using the light theme with light theme style.

    Chart using dark theme with default light theme background of #FFFFFF:

    Chart displayed using the dark theme with light theme style.

    Chart using dark theme with default dark theme background of #21313C:

    Chart displayed using the dark theme with dark theme style.

Iframe Example

The following iframe embeds a chart with the dark theme with the default dark theme inline style properties. The code is formatted for readability.

<iframe style="
background: #21313C;border: none;border-radius: 2px;
box-shadow: 0 2px 10px 0 rgba(70, 76, 79, .2);"
width="640" height="480" src="
https://charts.mongodb.com/charts-crllr/embed/charts?id=a1b2c3d4-a1b2-c3d4-9766-47b0b2daaff3&
theme=dark
"></iframe>

Remove the MongoDB Logo

Use the attribution query parameter with a value of false to display your embedded chart without the MongoDB logo.

The following iframe snippet renders a chart that does not display the MongoDB logo:

<iframe
style="background: #FFFFFF;border: none;border-radius: 2px;
box-shadow: 0 2px 10px 0 rgba(70, 76, 79, .2);"
width="640" height="480" src="
https://charts.mongodb.com/mongodb-charts-twsqq/embed/charts
?id=a1b2c3d4-a1b2-c3d4-9766-47b0b2daaff3&
theme=light&
attribution=false
"></iframe>

Auto Refresh and Data Caching Behavior

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.