jQuery Common - Utils - viz

An object that serves as a namespace for DevExtreme Data Visualization Components.

currentPalette()

Gets the current palette's name.

import { currentPalette } from "devextreme/viz/palette"
Return Value:

String

The current palette's name.

jQuery
index.js
var paletteName = DevExpress.viz.currentPalette();
// ===== or when using modules =====
import { currentPalette } from 'devextreme/viz/palette';

let paletteName = currentPalette();
Angular
app.component.ts
import { currentPalette } from 'devextreme/viz/palette';

let paletteName = currentPalette();
Vue
App.vue
import { currentPalette } from 'devextreme/viz/palette';

let paletteName = currentPalette();
React
App.js
import { currentPalette } from 'devextreme/viz/palette';

let paletteName = currentPalette();

currentPalette(paletteName)

Changes the current palette for all data visualization UI components on the page.

import { currentPalette } from "devextreme/viz/palette"
Parameters:
paletteName:

String

A new palette's name.

Only the UI components created after calling this method use the new palette. Refresh the styling settings in other UI components using the DevExpress.viz.refreshTheme() method.

See Also

currentTheme()

Gets the current theme's name.

import { currentTheme } from "devextreme/viz/themes"
Return Value:

String

The current theme's name.

currentTheme(platform, colorScheme)

Changes the current theme for all data visualization UI components on the page. The color scheme is defined separately.

import { currentTheme } from "devextreme/viz/themes"
Parameters:
platform:

String

The platform name or "generic".

colorScheme:

String

The color scheme: "light" or "dark".

Only the UI components created after calling this method use the new theme. Refresh the styling settings in other UI components using the DevExpress.viz.refreshTheme() method.

See Also

currentTheme(theme)

Changes the current theme for all data visualization UI components on the page.

import { currentTheme } from "devextreme/viz/themes"
Parameters:
theme:

String

The new theme's name.

Only the UI components created after calling this method use the new theme. Use the DevExpress.viz.refreshTheme() method to refresh the styling settings in other UI components.

See Also

exportFromMarkup(markup, options)

Allows you to export UI components using their SVG markup.

import { exportFromMarkup } from "devextreme/viz/export"
Parameters:
markup:

String

The SVG markup of the UI components you want to export.

options:

Object

Export properties.

Object structure:
Name Type Description
backgroundColor

String

The color that fills transparent regions.

fileName

String

The name of the file to be saved.

format

String

The file's format. One of 'PNG', 'PDF', 'JPEG', 'SVG' and 'GIF'.
PNG is used if the browser does not support exporting to the specified format.

height

Number

The SVG block's height in pixels. This field is required.

margin

Number

An empty space to be added around the exported SVG block; measured in pixels.

onExported

Function

Allows you to notify a user when exporting completes.

onExporting

Function

Allows you to request exporting details and prevent exporting.
The parameter contains the following fields:

  • fileName - the name of the file to be saved.
  • format - the file's format. One of 'PNG', 'PDF', 'JPEG', 'SVG' and 'GIF'.
  • cancel - when assigned true, prevents exporting.
onFileSaving

Function

Allows you to access exported data and/or prevent it from being saved to a file on the user's local storage.
The parameter contains the following fields:

  • fileName - the name of the file to be saved.
  • format - the file's format. One of 'PNG', 'PDF', 'JPEG', 'SVG' and 'GIF'.
  • data - exported data as a BLOB.
  • cancel - when assigned true, prevents the file from being saved.
svgToCanvas

Function

A function that renders SVG markup on the HTML canvas. Refer to the svgToCanvas description for details.

width

Number

The SVG block's width in pixels. This field is required.

IMPORTANT
We recommend that you do not use the foreignObject element to define markup (Safari does not support this element).

View Demo

See Also

exportWidgets(widgetInstances)

Exports one or several UI components to PNG.

import { exportWidgets } from "devextreme/viz/export"
Parameters:
widgetInstances:

Array<Array<dxChart | PieChart | Funnel | Sankey | TreeMap | VectorMap | Sparkline | Bullet | dxBarGauge>>

An array with the following format:

[
    [ widgetInstance0_1, widgetInstance0_2, ..., widgetInstance0_N ],
    [ widgetInstance1_1, widgetInstance1_2, ..., widgetInstance1_M ],
    ...
    [ widgetInstanceP_1, widgetInstanceP_2, ..., widgetInstanceP_R ]
]

Each nested array contains UI component instances that should be in the same row in the exported document.

exportWidgets(widgetInstances, options)

Exports one or several UI components.

import { exportWidgets } from "devextreme/viz/export"
Parameters:
widgetInstances:

Array<Array<dxChart | PieChart | Funnel | Sankey | TreeMap | VectorMap | Sparkline | Bullet | dxBarGauge>>

An array with the following format:

[
    [ widgetInstance0_1, widgetInstance0_2, ..., widgetInstance0_N ],
    [ widgetInstance1_1, widgetInstance1_2, ..., widgetInstance1_M ],
    ...
    [ widgetInstanceP_1, widgetInstanceP_2, ..., widgetInstanceP_R ]
]

Each nested array contains UI component instances that should be in the same row in the exported document.

options:

Object

Export properties.

Object structure:
Name Type Description
backgroundColor

String

The background color.

fileName

String

The name of the file to be saved.

format

ExportFormat

The file's format. PNG is used if the browser cannot export the file in the specified format.

gridLayout

Boolean

If true, UI components are arranged in columns with equal widths (the width of the widest UI component).
If false, UI components are placed next to each other in rows (default).
In any case, each row has the height of the highest UI component in it.

horizontalAlignment

HorizontalAlignment

Horizontally aligns UI components in their columns. Applies only when gridLayout is true.

margin

Number

Margins to be added to each side of the document; measured in pixels.

onExported

Function

Allows you to notify a user when the export is completed.

onExporting

Function

Allows you to request export details and prevent export.
The parameter contains the following fields:

  • fileName - the name of the file to be saved.
  • format - the file's format. One of 'PNG', 'PDF', 'JPEG', 'SVG' and 'GIF'.
  • cancel - prevents export when assigned true.
onFileSaving

Function

Allows you to access exported data and/or prevent it from being saved to a file in the user's local storage.
The parameter contains the following fields:

  • fileName - the name of the file to be saved.
  • format - the file's format. One of 'PNG', 'PDF', 'JPEG', 'SVG' and 'GIF'.
  • data - exported data as a BLOB.
  • cancel - when assigned true, prevents the file from being saved.
svgToCanvas

Function

A function that renders SVG markup on the HTML canvas. Refer to the svgToCanvas description for details.

verticalAlignment

VerticalAlignment

Vertically aligns UI components in their rows.

generateColors(palette, count, options)

Returns a subset of palette colors.

import { generateColors } from "devextreme/viz/palette"
Parameters:
palette:

Palette

|

Array<String>

A palette name or an array of colors. See palette for more information.

count:

Number

The number of colors in the resulting subset.

options:

Object

Optional settings.

Object structure:
Name Type Description
baseColorSet

PaletteColorSet

The color set that provides the colors. The default value is "simpleSet".
See getPalette(paletteName) for more information.

paletteExtensionMode

PaletteExtensionMode

The mode in which the palette should be extended when it contains less colors than specified in the count parameter. The default value is "blend".
See paletteExtensionMode for more information.

Return Value:

Array<String>

Colors in hexadecimal format.

The following code generates ten colors from the Material palette's gradient color set:

jQuery
index.js
var colors = DevExpress.viz.generateColors('Material', 10, { baseColorSet: 'gradientSet' });
// ===== or when using modules =====
import { generateColors } from 'devextreme/viz/palette';

let colors = generateColors('Material', 10, { baseColorSet: 'gradientSet' });
Angular
app.component.ts
import { generateColors } from 'devextreme/viz/palette';

let colors = generateColors('Material', 10, { baseColorSet: 'gradientSet' });
Vue
App.vue
import { generateColors } from 'devextreme/viz/palette';

let colors = generateColors('Material', 10, { baseColorSet: 'gradientSet' });
React
App.js
import { generateColors } from 'devextreme/viz/palette';

let colors = generateColors('Material', 10, { baseColorSet: 'gradientSet' });

Use the generated colors to paint elements of different UI components in identical colors. For instance, you can assign the same colors to series in two different charts to indicate the visualized information is connected.

getMarkup(widgetInstances)

Gets the SVG markup of specific UI components for their subsequent export.

import { getMarkup } from "devextreme/viz/export"
Parameters:
widgetInstances:

Array<Array<dxChart | PieChart | Funnel | Sankey | TreeMap | VectorMap | Sparkline | Bullet | dxBarGauge>>

The UI component instances.

Return Value:

String

The UI components' SVG markup. Pass it to the exportFromMarkup(markup, options) method to export the UI components.

See Also

getPalette(paletteName)

Gets the color sets of a predefined or registered palette.

import { getPalette } from "devextreme/viz/palette"
Parameters:
paletteName:

String

The palette's name.

Return Value:

Object

The palette's settings.

The returned value is an object of the following structure:

JavaScript
{
    // Applies in the BarGauge, Chart, Funnel, PieChart, PolarChart, Sankey, and TreeMap with a discrete colorizer
    simpleSet: ['#60a69f', '#78b6d9', '#6682bb', '#a37182', '#eeba69'], 
    // Applies in the CircularGauge and LinearGauge
    indicatingSet: ['#90ba58', '#eeba69', '#a37182'], 
    // Applies in the VectorMap and TreeMap with a gradient or range colorizer 
    gradientSet: ['#78b6d9', '#eeba69'] 
}

The built-in palettes are listed in the Appearance Customization topic.

getTheme(theme)

Gets a predefined or registered theme's settings.

import { getTheme } from "devextreme/viz/themes"
Parameters:
theme:

String

The theme's name.

Return Value:

Object

The theme's settings.

map

An object that serves as a namespace for the VectorMap UI component.

refreshPaths()

The method to be called every time the active entry in the browser history is modified without reloading the current page.

import { refreshPaths } from "devextreme/viz/utils"

Each data visualization UI component addresses its inner elements by their URLs. Those URLs break when the active history entry is modified without reloading the current page (see Adding and modifying history entries). As a result, some UI component elements may get mixed up or disappear completely. To fix the URLs, call the refreshPaths() method right after the history entry modification, and in the onpopstate event handler or, if you use a routing library, in its counterpart.

JavaScript
window.history.pushState({ foo: "bar" }, "title", "?foo=bar");
DevExpress.viz.refreshPaths();

window.onpopstate = function(event) {
    DevExpress.viz.refreshPaths();
}

The problem with broken URLs may also emerge if the page uses a path modifying HTML tag; for example, <base> or <iframe>. To resolve it, set the pathModified property of the UI component to true.

refreshTheme()

Refreshes the current theme and palette in all data visualization UI components on the page.

import { refreshTheme } from "devextreme/viz/themes"

registerGradient(type, options)

Registers a new gradient.

import { registerGradient } from "devextreme/common/charts"
Parameters:
type:

String

Gradient type: 'linear' or 'radial'.

options:

Object

Gradient's settings.

Object structure:
Name Type Description
colors

Array<GradientColor>

An array of gradient colors.

rotationAngle

Number

Linear gradient rotation angle.

Return Value:

String

Fill ID.

Call this method to register a gradient ID. Assign the ID to a component's color.fillId field.

jQuery
index.js
const registerGradient = DevExpress.common.charts.registerGradient;

$(() => {
    $('#chart').dxChart({
        // ...
        commonSeriesSettings: {
            color: {
                base: "#f5564a",
                fillId: registerGradient("linear", {
                    colors: [{
                        offset: "20%",
                        color: "#97c95c"
                    }, {
                        offset: "90%",
                        color: "#eb3573"
                    }]
                })
            }
        }
    });
});
Angular
app.component.html
app.component.ts
<dx-chart ... >
    <dxo-common-series-settings [color]="seriesColor">
    </dxo-common-series-settings>
</dx-chart>
import { registerGradient } from "devextreme/common/charts";

export class AppComponent {
    seriesColor = {
        base: "#f5564a",
        fillId: registerGradient("linear", {
            colors: [{
                offset: "20%",
                color: "#97c95c"
            }, {
                offset: "90%",
                color: "#eb3573"
            }]
        });
    };
}
Vue
App.vue (Options API)
App.vue (Composition API)
<template>
    <DxChart ... >
        <DxCommonSeriesSettings 
            :color="seriesColor"
        />
    </DxChart>
</template>
<script>
    import DxChart, { DxCommonSeriesSettings } from 'devextreme-vue/chart';
    import { registerGradient } from 'devextreme/common/charts';

    export default {
        components: {
            DxChart,
            DxCommonSeriesSettings
        },
        data() {
            return {
                // ...
                seriesColor: {
                    base: '#f5564a',
                    fillId: registerGradient("linear", {
                        colors: [{
                            offset: "20%",
                            color: "#97c95c"
                        }, {
                            offset: "90%",
                            color: "#eb3573"
                        }]
                    })
                }
            }
        }
    };
</script>
<template>
    <DxChart ... >
        <DxCommonSeriesSettings 
            :color="seriesColor"
        />
    </DxChart>
</template>
<script setup>
    import DxChart, { DxCommonSeriesSettings } from 'devextreme-vue/chart';
    import { registerGradient } from 'devextreme/common/charts';

    // ...

    const seriesColor = {
        base: '#f5564a',
        fillId: registerGradient("linear", {
            colors: [{
                offset: "20%",
                color: "#97c95c"
            }, {
                offset: "90%",
                color: "#eb3573"
            }]
        })
    };
</script>
React
App.js
import Chart, { CommonSeriesSettings } from 'devextreme-react/chart';
import { registerGradient } from 'devextreme/common/charts';

const seriesColor = {
    base: "#f5564a",
    fillId: registerGradient("linear", {
        colors: [{
            offset: "20%",
            color: "#97c95c"
        }, {
            offset: "90%",
            color: "#eb3573"
        }]
    })
};

export default function App() {
    return (
        <Chart ... >
            <CommonSeriesSettings 
                color={seriesColor}
            />
        </Chart>
    );
}
NOTE
  • To correctly export a component with transparent gradient, specify gradient colors in RGBA format.

  • Radial and rotated linear gradients may look slightly different when exported.

View Demo

registerPalette(paletteName, palette)

Registers a new palette.

import { registerPalette } from "devextreme/viz/palette"
Parameters:
paletteName:

String

The palette's name.

palette:

Object

The palette's settings.

The palette settings is an object of the following structure:

JavaScript
{
    // Applies in the BarGauge, Chart, Funnel, PieChart, PolarChart, Sankey, and TreeMap with a discrete colorizer
    simpleSet: ['#60a69f', '#78b6d9', '#6682bb', '#a37182', '#eeba69'], 
    // Applies in the CircularGauge and LinearGauge
    indicatingSet: ['#90ba58', '#eeba69', '#a37182'], 
    // Applies in the VectorMap and TreeMap with a gradient or range colorizer 
    gradientSet: ['#78b6d9', '#eeba69'] 
}

registerPattern(options)

Registers a new pattern.

import { registerPattern } from "devextreme/common/charts"
Parameters:
options:

Object

Pattern settings.

Object structure:
Name Type Description
height

Number

|

String

Template height.

template

Function

SVG-based pattern template.

width

Number

|

String

Template width.

Return Value:

String

Fill ID.

Call this method to register a pattern ID. Assign the ID to a component's color.fillId field.

The following example demonstrates how to create a stroke pattern. Use a d SVG attribute to draw a path for a pattern.

jQuery
index.js
const registerPattern = DevExpress.common.charts.registerPattern;

$(() => {
    $('#chart').dxChart({
        // ...
        commonSeriesSettings: {
            color: {
                base: "#f5564a",
                fillId: registerPattern({
                    width: 5,
                    height: 5,
                    template: (container) => {
                        const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
                        path.setAttribute('stroke', '#97c95c');
                        path.setAttribute('stroke-width', 1.5);
                        path.setAttribute('d', `M 2.5 -2.5 L -2.5 2.5 M 0 5 L 5 0 M 7.5 2.5 L 2.5 7.5`);
                        container.appendChild(path);
                    },
                })
            }
        }
    });
});
Angular
app.component.html
app.component.ts
<dx-chart ... >
    <dxo-common-series-settings [color]="seriesColor">
    </dxo-common-series-settings>
</dx-chart>
import { registerPattern } from "devextreme/common/charts";

export class AppComponent {
    seriesColor = {
        base: "#f5564a",
        fillId: registerPattern({
            width: 5,
            height: 5,
            template: (container) => {
                const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
                path.setAttribute('stroke', '#97c95c');
                path.setAttribute('stroke-width', 1.5);
                path.setAttribute('d', `M 2.5 -2.5 L -2.5 2.5 M 0 5 L 5 0 M 7.5 2.5 L 2.5 7.5`);
                container.appendChild(path);
            },
        })
    };
}
Vue
App.vue (Options API)
App.vue (Composition API)
<template>
    <DxChart ... >
        <DxCommonSeriesSettings 
            :color="seriesColor"
        />
    </DxChart>
</template>
<script>
    import DxChart, { DxCommonSeriesSettings } from 'devextreme-vue/chart';
    import { registerPattern } from 'devextreme/common/charts';

    export default {
        components: {
            DxChart,
            DxCommonSeriesSettings
        },
        data() {
            return {
                // ...
                seriesColor: {
                    base: '#f5564a',
                    fillId: registerPattern({
                        width: 5,
                        height: 5,
                        template: (container) => {
                            const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
                            path.setAttribute('stroke', '#97c95c');
                            path.setAttribute('stroke-width', 1.5);
                            path.setAttribute('d', `M 2.5 -2.5 L -2.5 2.5 M 0 5 L 5 0 M 7.5 2.5 L 2.5 7.5`);
                            container.appendChild(path);
                        },
                    })
                }
            }
        }
    };
</script>
<template>
    <DxChart ... >
        <DxCommonSeriesSettings 
            :color="seriesColor"
        />
    </DxChart>
</template>
<script setup>
    import DxChart, { DxCommonSeriesSettings } from 'devextreme-vue/chart';
    import { registerPattern } from 'devextreme/common/charts';

    // ...

    const seriesColor = {
        base: '#f5564a',
        fillId: registerPattern({
            width: 5,
            height: 5,
            template: (container) => {
                const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
                path.setAttribute('stroke', '#97c95c');
                path.setAttribute('stroke-width', 1.5);
                path.setAttribute('d', `M 2.5 -2.5 L -2.5 2.5 M 0 5 L 5 0 M 7.5 2.5 L 2.5 7.5`);
                container.appendChild(path);
            },
        })
    };
</script>
React
App.js
import Chart, { CommonSeriesSettings } from 'devextreme-react/chart';
import { registerPattern } from 'devextreme/common/charts';

const seriesColor = {
    base: "#f5564a",
    fillId: registerPattern({
        width: 5,
        height: 5,
        template: (container) => {
            const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
            path.setAttribute('stroke', '#97c95c');
            path.setAttribute('stroke-width', 1.5);
            path.setAttribute('d', `M 2.5 -2.5 L -2.5 2.5 M 0 5 L 5 0 M 7.5 2.5 L 2.5 7.5`);
            container.appendChild(path);
        },
    })
};

export default function App() {
    return (
        <Chart ... >
            <CommonSeriesSettings 
                color={seriesColor}
            />
        </Chart>
    );
}
NOTE
For the component export to work correctly, the size of a pattern template must be specified in pixels or a CSS-specified measure of size (excluding percent).

View Demo

registerTheme(customTheme, baseTheme)

Registers a new theme based on the existing one.

import { registerTheme } from "devextreme/viz/themes"
Parameters:
customTheme:

Object

The theme's settings.

baseTheme:

String

The base theme's name.

For details on how to customize a theme, refer to the Themes article.