Embedded Charts SDK Options

On this page

Embedded Chart Options

Chart Configuration
getCustomizableAxes()
setAutoRefresh(boolean)
setPreFilter(object)
setFilter(object)
setMaxDataAge(number)
setRenderingSpecOverride(object)
setTheme("dark" | "light")
Example
Rendering Specification Options
Conditional Formatting Operators
Channels Example
Conditional Formatting Example

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 = new ChartsEmbedSDK({}).createChart({
  baseUrl: 'https://charts.mongodb.com/charts-rendering-spec-project-aygif',
  chartId: '38de4b38-42ea-422a-b702-a0220c8885e8',
  height: 300,
  width: 400,
  renderingSpec: {
    version: 1,
    title: 'Customized chart title',
    description: 'Customized chart description',
    axes: {
      y: {
        logScale: true
      },
    },
    channels: {
      x: {
        labelOverride: "New field label"
      },
      y: {
        numberSuffix: "%"
      }
    },
    options: {
      labelSize: 150,
      lineSmoothing: 'monotone'
    }
  }
});
await chart.render(embedContainer);

Embedded Chart Options

The createChart() method takes the following options:

Option	Type	Description	Required?
`autoRefresh`	boolean	Flag that indicates whether the chart automatically refreshes. If omitted, charts 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 a chart 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`: `#FFFFFF` for the `light` theme, or `#21313C` for the `dark` theme.	no
`baseUrl`	string	Base URL of the chart.	yes
`chartID`	string	Unique identifier of the chart.	yes
`preFilter`	object	Pre-Filter to apply to the chart. Pre-filters run before the chart's query execution starts.	no
`filter`	object	Filter to apply to the chart.	no
`getUserToken`	object	Function that returns a `base64`-encoded JWT token. Charts validates this token to determine if Charts renders an authenticated chart. If authenticated access is enabled, Charts renders the authenticated chart view only if Charts can validate the token using the configured authentication providers. If the token is invalid, Atlas Charts renders the unauthenticated chart if you enabled unauthenticated access. Otherwise, Charts doesn't render the chart. To learn more, see Embed an Authenticated Chart using a Custom JWT Provider.	no
`height`	number	Height of the chart. If omitted, the chart defaults to the height of its container. If you provide a value without units, the unit defaults to pixels (px).	no
`maxDataAge`	number	Specifies the maximum age of data to load from the cache when loading or refreshing the chart. If omitted, Atlas 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. To learn how Atlas Charts loads data from the cache when loading or refreshing the chart based on the `autoRefresh` and `maxDataAge` values, see Refresh and Data Caching Behavior.	no
`renderingSpec`	object	Rendering specification that specifies how to customize an embedded chart. For a list of available customizations, see Rendering Specification Options.	no
`showAttribution`	boolean	Flag that indicates whether to display the MongoDB logo below the chart. Defaults to `true`.	no
`theme`	string	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
`width`	number	Width of the chart. If omitted, the chart defaults to the width of its container. If you provide a value without units, it defaults to pixels (px).	no

Chart Configuration

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

`getCustomizableAxes()`

Returns the chart axes for the embedded chart.

`setAutoRefresh(boolean)`

Specifies whether the chart automatically refreshes. If omitted, charts don't automatically refresh.

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

`setPreFilter(object)`

Applies a query pre-filter to the embedded chart or chart within an embedded dashboard. This method takes an object with valid query operators. Add fields referenced in this pre-filter to the Allowed filter fields list in the Embed Chart modal window. An empty document {} means you omit the pre-filter.

To learn more about enabling embedding for a chart and applying pre-filters, see the Embedding Tutorials.

`setFilter(object)`

Applies a query filter to the embedded chart or chart within an embedded dashboard. This method takes an object with valid query operators. Any fields referenced in this filter must be added to the Allowed filter fields list in the Embed Chart modal window. An empty document {} is equivalent to no filter.

To learn more about enabling embedding for a chart and applying filters, see the Embedding Tutorials.

`setMaxDataAge(number)`

Specifies the maximum age of data to load from the cache when loading or refreshing the chart. If omitted, Atlas 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.

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

`setRenderingSpecOverride(object)`

Specifies how to customize a chart.

For a list of available customizations, see Rendering Specification Options.

`setTheme("dark" | "light")`

Sets the current theme of the embedded chart. When setting the theme to dark, you need to ensure that a chart's background color has appropriate contrast so that the information remains visible.

Tip

Example

The following example configures a Chart instance named chart to use the dark theme and to refresh every 60 seconds.

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

Rendering Specification Options

You can specify the following options for the renderingSpec object:

Note

All options, except version are optional.

Option

Type

Description

axes

object

Object that describes how to customize the charts axes.

axes

.labelOverride

string

Value to replace the current axes label.

To learn more, see Label Override.

axes

.labelAngle

enum

Angle at which to display a label.

Value can be one of the following: 'vertical', 'horizontal', 'diagonal'

This applies to All Column, 100% Stacked Area, Area Discrete, Line Discrete, Grouped Combo, Stacked Combo, and Heatmap charts.

To learn more, see Adjust X-Axis Label Angle.

axes

.logScale

boolean

Flag that indicates whether to use the logorithmic scale for the data values on a chart.

This only applies to Grouped Column, Colored Column, Grouped Bar, Colored Bar, Line Continuous, Line Discrete, Grouped Combo, and Scatter charts.

To learn more, see Logarithmic Scale.

axes

.scaleMax

number | false

Maximum value to display on the chart. false makes this option behave in its default state.

This only applies to Grouped Column, Colored Column, Stacked Column, Grouped Bar, Colored Bar, Stacked Bar, Area Continuous, Area Discrete, Line Continuous, Line Discrete, Scatter, Grouped Combo, Stacked Combo, and Gauge charts.

To learn more, see Max and Min.

axes

.scaleMin

number | false

Minimum value to display on the chart. false makes this option behave in its default state.

To learn more, see Max and Min.

channels

object

Object that describes how to customize the charts channels.

channels

.labelOverride

string

Value to replace the current channel label.

To learn more, see Field Label Override.

channels

.numberDecimals

number

Amount of decimal places to round each numeric data value or label.

To learn more, see Number Formats.

channels

.numberMultiplier

number

Number to multiply each numeric data value or label by.

To learn more, see Number Formats.

channels

.numberPrefix

string

String to prepend to each numeric data value or label.

To learn more, see Number Formats.

channels

.numberSuffix

string

String to append to the end of each numeric data value or label.

To learn more, see Number Formats.

channels

.numberThousandsSeparators

boolean

Flag that indicates whether to show commas as thousands separators for numeric data values.

To learn more, see Number Formats.

channels

.plotOnSecondaryAxis

boolean

Flag that indicates whether to plot a set a field that correspond to a channel on a secondary Y axis.

This only applies to Area Continuous, Grouped Column, Grouped Combo, Stacked Combo, Line Continuous, and Line Discrete charts.

To learn more, see Secondary Y Axis.

channels

.wrapText

boolean

Flag that indicates whether to wrap the text for Table Charts.

To learn more, see Wrap Text.

conditionalFormatting

object

Object that describes how to format a section of a chart.

To learn more, see Conditional Formatting.

conditionalFormatting

.applyToEntireRow

boolean

Flag that indicates whether to apply the specified format to an entire row.

conditionalFormatting

.backgroundColor

enum | string

Object that indicates how to customize the background color.

Value can be one of the following:

Conditional Rules	Type	Values
`'continuous'`	enum	`'redwhitegreen'` `'redwhiteblue'` `'yellowgreen'` `'redyellowgreen'` `'greenwhite'` `'bluewhite'` `'redwhite'`
`'discrete'`	string	Resembles the RGB color model, hexidecimal color, or the name of a color. If you specify `'transparent'`, the previous color applies, if any.

conditionalFormatting

.conditions

array

This applies to both 'continuous' and 'discrete' conditional rules.

Conditional Rules	Description
`'continuous'`	Object that describes how to format the `targetChannel`. This applies to Table charts.
`'discrete'`	Object that describes how to format the `targetChannel`. This applies to Table and Number charts.

conditionalFormatting
.conditions
.operator

NumericOperator
NumericBinnedOperator
StringOperator
StringRegexOperator
DateOperator
DateBinnedOperator

Operator to apply to your 'discrete' conditional rules.

This applies to Table and Number charts.

To learn more about the valid operators, see Conditional Formatting Operators.

conditionalFormatting
.conditions
.targetChannel

string

Table column that receives the continuous color for 'continuous' or 'discrete' conditional rules.

This applies to 'continuous' and 'discrete' Table charts, and 'discrete' Number charts.

conditionalFormatting
.conditions
.targetType

enum

Part of the Table chart to apply the operator and value for 'discrete' conditional rules.

Value can be one of the following: 'CHANNEL', 'ROW_INDEX', 'COLUMN_NAME', 'CELL_VALUE', 'ROW_TOTAL', 'COLUMN_TOTAL', 'COLUMN_ID'

conditionalFormatting
.conditions
.value

number
string
array of strings
object

Value to apply to the operator for 'discrete' conditional rules. The data type depends on the operator you select.

This applies to Table and Number charts.

conditionalFormatting

.fontStyle

enum

Font to use for 'discrete' conditional rules.

Value can be one of the following: 'italic', 'normal'

This applies to Table and Number charts.

conditionalFormatting

.fontWeight

enum

Font weight for 'discrete' conditional rules.

Value can be one of the following: 'bold', 'normal'

This applies to Table and Number charts.

conditionalFormatting

.reverseColor

boolean

Flag that indicates whether to reverse the chosen continuous color for 'continuous' conditional rules.

This only applies to Table charts.

conditionalFormatting

.textColor

string

Text color for 'discrete' conditional rules.

Value must be a string that resembles the RGB color model, hexidecimal color, or the name of a color. If you specify 'auto', no color applies.

conditionalFormatting

.textDecoration

enum

Text decoration for 'discrete' conditional rules.

Value can be one of the following: 'underline', 'line-through', 'underline line-through', 'initial'

This applies to Table and Number charts.

conditionalFormatting

.type

enum

Type of conditional rules your chart uses.

Value can be one of the following: 'discrete', 'continuous'

The 'discrete' conditional rules applies to Table and Number charts.

The 'continuous' conditional rules applies to Table charts.

description

string

Description of the chart.

options

object

Object that describes how to customize the chart's options.

options

.categoryLabels

boolean

Flag that indicates whether to show the category labels in a donut chart.

To learn more, see Show or Hide Category Labels.

options

.colorPalette

object | false

Object that describes how to customize the color palette. false unsets any custom color palette that you set from the Chart Builder.

To learn more, see Color Palette Customization.

options
.colorPalette
.channels

array

Names of the channels to receive a custom color.

options
.colorPalette
.color

object

Object that describes how to customize the color palette.

This applies to all chart types that can have multiple fields in the series channel: all Bar charts except Colored Bar, all Column charts except Colored Column and Candlestick, Grouped Combo, Stacked Combo, all Line charts, all Area charts, and Donut.

options
.colorPalette
.marks

array

Encoded field values in the series channel to receive a custom color.

This applies to all chart types that can have multiple series in a channel.

For array's that contain the values positive and negative, this only applies to candlestick charts.

options
.colorPalette
.reverseColor

boolean

Flag that indicates whether to reverse the continuous continuous color.

options
.colorPalette
.type

enum

Type of color palette your chart uses.

Value can be one of the following: 'discrete', 'continuous'

The 'discrete' color palette applies to the following chart types: Grouped Bar, Stacked Bar, 100% Stacked Bar, Grouped Column, Stacked Column, 100% Stacked Column, Area Continuous, Area Discrete, 100% Stacked Area, Line Continuous, Line Discrete, Candlestick, Scatter, Donut, Geo Scatter, Word Cloud, Gauge, Grouped Combo, and Stacked Combo.

The 'continuous' color palette applies to the following chart types: Colored Column, Colored Bar, Geo Heatmap, Geo Choropleth, and Heatmap.

options
.colorPalette
.values

array

Color values to customize the colors for single series charts or the channels and marks for multi-series charts.

options

.labelSize

number | false

Size to change a label to. The size should be between 50 and 200. false is equivalent to setting the size to 100, and makes this option behave in its default state.

To learn more, see Resize Labels.

options

.legendPosition

enum

Location to place a legend in relation to the chart. This only applies to charts that support legends.

Value can be one of the following: 'right', 'bottom', 'top'

To learn more, see Customize Legend.

options

.lineSmoothing

enum

Method that Charts uses to draw a line on a chart.

Value can be one of the following: 'linear', 'monotone', 'step-before', 'step-after'

This only applies to Area Continuous, Area Discrete, 100% Stacked Area, Line Continuous,Line Discrete, Grouped Combo, and Stacked Combo charts.

To learn more, see Smooth Lines.

options

.markers

boolean

Flag that indicates whether to display visible data markers that represent individual data points.

To learn more, see Show or Hide Data Markers.

options

.textSize

number | false

Size of the text on a chart. false makes this option behave in its default state.

To learn more, see Resize Table Text.

options

.totalsColumn

boolean

Flag that indicates whether to display the total sum of each column.

To learn more, see Toggle Table Row and Column Totals.

options

.totalsRow

boolean

Flag that indicates whether to display the total sum of each row.

To learn more, see Toggle Table Row and Column Totals.

options

.valueLabels

enum

Method that Charts uses to display the exact value of a data point.

Value can be one of the following: 'value', 'percentage'

This applies to all Bar charts except 100% Stacked Bar, All Column charts except 100% Stacked Column, Area Continuous, Area Discrete, 100% Stacked Area, Line Continuous, Line Discrete, Grouped Combo, and Stacked Combo charts.

To learn more, see Label Override.

title

string

Title of the chart.

version

number

Version of the rendering specification. The first and current version is 1.

This is a required field.

Conditional Formatting Operators

The following table shows the available operators to use with conditional formatting, the data type they apply to, and their possible values.

Operator

Type

Values

DateBinnedOperator

object

BINNED_DATE_AFTER, BINNED_DATE_AFTER_OR_INCLUDES, BINNED_DATE_BEFORE, BINNED_DATE_BEFORE_OR_INCLUDES, BINNED_DATE_INCLUDES

The object must have the following keys:

date: string
time: string

DateOperator

object

DATE_AFTER, DATE_BEFORE, DATE_EXACTLY, DATE_ON_OR_AFTER, DATE_ON_OR_BEFORE

The object must have the following keys:

date: string
time: string

NumericBinnedOperator

number

BINNED_NUMBER_GREATER_THAN, BINNED_NUMBER_GREATER_THAN_OR_INCLUDES, BINNED_NUMBER_INCLUDES, BINNED_NUMBER_LESS_THAN, BINNED_NUMBER_LESS_THAN_OR_INCLUDES

NumericOperator

number

NUMBER_EQUAL_TO, NUMBER_GREATER_THAN, NUMBER_GREATER_THAN_OR_EQUAL_TO, NUMBER_LESS_THAN, NUMBER_LESS_THAN_OR_EQUAL_TO, NUMBER_NOT_EQUAL_TO, NUMBER_RANKED_IN_BOTTOM, NUMBER_RANKED_IN_BOTTOM_PERCENT, NUMBER_RANKED_IN_TOP, NUMBER_RANKED_IN_TOP_PERCENT

StringOperator

string | array of strings

STRING_CONTAINS, STRING_EMPTY, STRING_EQUAL_TO, STRING_NOT_CONTAINS, STRING_NOT_EMPTY, STRING_NOT_EQUAL_TO, STRING_ONE_OF, STRING_STARTS_WITH

StringRegexOperator

object

STRING_REGEX

The object must have the following keys:

source: regex string
flags: string

The value for flag can be one of the following:

Value	Description
`'i'`	Case insensitive.
`'m'`	Multiline.
`'x'`	Extended.
`'s'`	Single line.

Channels Example

The following example configures a Chart instance named chart with these options:

Use version 1 of the rendering specification.
Update the x encoding channel to:
- Not use commas for the thousand separator.
- Start all numeric values with a $.
Update the y encoding channel to end all numeric values with a %.
Update the color encoding channel to:
- Round all decimal values to two decimal places.
- Multiply all numeric values by two.
Use the continuous color palette type with the rainbow color, and to reverse the chosen continuous color.

await chart.setRenderingSpecOverride({
  version: 1,
  channels: {
    x: {
      numberThousandsSeparators: false,
      numberPrefix: '$',
    },
    y: {
      numberSuffix: '%',
    },
    color: {
      numberDecimals: 2,
      numberMultiplier: 2,
    },
  },
  options: {
    colorPalette: {
      type: 'continuous',
      color: 'rainbow',
      reverseColor: true,
    },
  },
});

Conditional Formatting Example

The following example configures a Chart instance named chart with these options:

Use version 1 of the rendering specification.
Perform the following conditional formatting to a CHANNEL where the value is greater than 200:
- Use the 'discrete' conditional formatting rules.
- Set the background color to an RGB color model where red is 240, green is 209, and blue is 117.
- Set the text color to red.
- Set the font style to 'italic'.
- Decorate the text with 'underline'.
For the value_series_0 column:
- Use the 'continuous' color palette.
- Set the background color to redyellowgreen.
- Reverse the chosen continuous color.

await chart.setRenderingSpecOverride({
  version: 1,
  conditionalFormatting: [{
    type: 'discrete',
    backgroundColor: 'rgb(240, 209, 117)',
    textColor: 'red',
    fontStyle: 'italic',
    fontWeight: 'bold',
    textDecoration: 'underline',
    applyToEntireRow: false,
    conditions: [{
        operator: 'NUMBER_GREATER_THAN',
        targetType: 'CHANNEL',
        targetChannel: 'value',
        value: 200,
    }],
  },{
    type: 'continuous',
    backgroundColor: 'redyellowgreen',
    reverseColor: true,
    conditions: [{ targetChannel: 'value_series_0' }],
  }],
});

Back

Options

iframe

Example

Embedded Chart Options

Chart Configuration

getCustomizableAxes()

setAutoRefresh(boolean)

setPreFilter(object)

setFilter(object)

setMaxDataAge(number)

setRenderingSpecOverride(object)

setTheme("dark" | "light")

Tip

See also:

Example

Rendering Specification Options

Note

Conditional Formatting Operators

Channels Example

Conditional Formatting Example

`getCustomizableAxes()`

`setAutoRefresh(boolean)`

`setPreFilter(object)`

`setFilter(object)`

`setMaxDataAge(number)`

`setRenderingSpecOverride(object)`

`setTheme("dark" | "light")`