Docs Menu
Docs Home
/
Atlas Charts
/ / /

Embedded Charts SDK Options

On this page

  • Embedded Chart Options
  • Chart Configuration
  • getCustomizableAxes()
  • setAutoRefresh(boolean)
  • 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);

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
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.

Tip

See also:

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

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

Returns the chart axes for the embedded chart.

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.

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.

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

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.

Specifies how to customize a chart.

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

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.

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);

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.

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.

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.

Note

This is a required field.

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

Note

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

Note

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

Note

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.

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,
},
},
});

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' }],
}],
});
← Embedded Chart Options