Appearance Customization

To define an appearance for your widget, you can use themes and palettes. Themes determine the overall look and feel of a widget by painting its visual elements. Palettes are sets of colors for painting chart series or points. The documents in this section explain these concepts in greater detail.

Themes

The DevExtreme data visualization widgets consist of many elements, each of which has options that determine appearance. The default values of appearance options are united in a theme.

DevExtreme provides several predefined platform-specific themes: 'desktop', 'ios', 'android' and 'win8'. When running a page with DevExtreme widgets, apply the corresponding platform-specific theme. For this purpose, use the DevExpress.viz.core.currentTheme method passing the name of the required theme as a parameter.

JavaScript
DevExpress.viz.core.currentTheme('android');

To determine on which platform the page is currently running, use the platform field of the object returned by the DevExpress.devices.current() method. Since the possible values of the platform field coincide with the names of the predefined themes, use the following code to automatically set the appropriate theme for widgets on the page.

JavaScript
DevExpress.viz.core.currentTheme(DevExpress.devices.current().platform);

In addition to the theme name, you can specify the required color scheme. For this purpose, pass 'light' or 'dark' as the second parameter of the currentTheme method.

JavaScript
DevExpress.viz.core.currentTheme(DevExpress.devices.current().platform, 'light');

If you do not set the required theme, the "desktop" theme is applied.

You can customize the applied themes by setting custom values when defining the widget's configuration object. However, if you need to have a custom theme, implement a new theme. In this topic, you will learn how to implement and use a custom theme.

Show Example:
jQuery
<div id="chartContainer" style="height:500px; max-width:700px; margin: 0 auto"></div>
var myTheme = {
    name: 'myCoolTheme',
    chart: {
        commonSeriesSettings: {	
            label: {
                connector:{
                    visible: true,           
                    width: 2
                }
            }
        }
    }
};
DevExpress.viz.core.registerTheme(myTheme,'desktop');
var dataSource = [
    {cat: 'A', bar: 1.5, line: 4.9},
    {cat: 'B', bar: 1.9, line: 3.3},
    {cat: 'C', bar: 1.5, line: 4.0},
    {cat: 'D', bar: 5.2, line: 1.2},
    {cat: 'E', bar: 3.1, line: 2.5}
];
var series = [
    {
        argumentField: 'cat',
        valueField: 'bar',
        type: 'bar',
        label: {visible: true}
    },
    {
        argumentField: 'cat',
        valueField: 'line',
        type: 'line',
        label: {visible: true}
    }
];
$("#chartContainer").dxChart({
    theme: 'myCoolTheme',
    dataSource: dataSource,
    series: series
});

Customize a Theme

If you are satisfied with the majority of option values in the applied predefined theme, but need a few of the option values changed, customize the theme. For this purpose, do the following.

  • Introduce an object for a new theme and give a name to it.

    JavaScript
    var myTheme = {
        name: 'myCustomTheme',  
    };
  • Specify the required settings for each widget you use within separate objects.

    JavaScript
    var myTheme = {
        name: 'myCustomTheme',
        chart: {
            // Theme options for dxChart
        },
        pie: {
            // Theme options for dxPieChart
        },
        gauge: {
            // Theme options for dxCircularGauge and dxLinearGauge
        },
        barGauge: {
            // Theme options for dxBarGauge
        },
        rangeSelector: {
            // Theme options for dxRangeSelector
        },
        bullet: {
            // Theme options for dxBullet
        },
        sparkline: {
            // Theme options for dxSparkline
        },
        map: {
            // Theme options for dxVectorMap
        }
    };

    The options that can be set in a theme are described in the Reference section.

  • Register your theme, indicating the theme that your theme is based on. For this purpose, use the registerTheme method.

    JavaScript
    DevExpress.viz.core.registerTheme(myTheme,'desktop');

Implement a Custom Theme

You can implement an entirely custom theme. For this purpose, do the following.

  • Introduce an object for a new theme and give a name to it.

    JavaScript
    var myTheme = {
        name: 'myCustomTheme',  
    };
  • Specify all the theme settings. The options that are set in a theme are described in the Reference section.

  • Register your theme. For this purpose, use the registerTheme method.

    JavaScript
    DevExpress.viz.core.registerTheme(myTheme);

Apply a Custom Theme

To apply a custom theme for all widgets on the page, use the DevExpress.viz.core.currentTheme method passing the name of your theme as a parameter.

JavaScript
DevExpress.viz.core.currentTheme('myCustomTheme');

To use a custom theme for a particular widget only, set the theme name to the theme configuration option.

JavaScript
$("#chartContainer").dxChart({
    theme: 'myCustomTheme',
    //...   
});

Palettes

Certain charts contain several series at a time. Similarly, the gauge range container can contain several ranges, and a vector map consists of several areas. In such instances, a color would need to be set for each series, range or area individually. Instead, you can use built-in palettes - sets of colors.

Palettes can be specified and used in the following widgets.

  • dxChart
  • dxPieChart
  • dxCircularGauge
  • dxLinearGauge
  • dxBarGauge
  • dxVectorMap

By using the palettes, you can be sure that the colors mix well with each other and create beautiful charts. If the number of series (in dxChart), series points (in dxPieChart), ranges (in dxCircularGauge and dxLinearGauge), bars (in dxBarGauge) or areas (in dxVectorMap) is greater than the number of colors in the palette, the palette colors are repeated with a slight modification.

The following built-in palettes are available.

Palette Default Palette Soft Pastel Palette Harmony Light Palette Pastel Palette Bright Palette Soft Palette Ocean Palette Vintage Palette Violet

The "default" palette is used by default. To apply another palette, use the palette option.

JavaScript
$("#chartContainer").dxChart({
    palette: 'Soft Pastel',
    //...   
});

The following subsections provide information about the available palette customizations.

Ignore Palette Colors

If you use a predefined palette, you can still set a custom color for a particular series, range or area using the color option.

JavaScript
$("#chartContainer").dxChart({
    series: [{
        color: 'red'
        //...
    }, {...}, ...]
});

$("#gaugeContainer").dxCircularGauge({
    rangeContainer: {
        ranges: [{
            color: 'red'
            //...
        }, {...}, ...]
    }
});

$("#mapContainer").dxVectorMap({
    areaSettings: {
        customize: function() {
            return {
                color: 'red'
                //...
            }
        }
    }
});

NOTE: This approach cannot be used in dxBarGauge.

Declare a Custom Palette

You can set a custom palette for a chart, gauge or map using the palette configuration option. Assign an array of colors to this field.

JavaScript
$("#chartContainer").dxChart({
    palette: ['#7CBAB4', '#92C7E2', '#75B5D6', '#B78C9B', '#F2CA84', '#A7CA74'],
    //...   
});

NOTE: When you use this approach for a vector map, assign an array with only two colors to the palette option. See the Reference for specific details on using palettes in dxVectorMap.

Implement a Custom Palette

To use a custom palette in different charts, gauges and maps define and register that palette in the following way.

JavaScript
var myPalette = {
    simpleSet: ['#60a69f', '#78b6d9', '#6682bb', '#a37182', '#eeba69'], // for dxChart, dxPieChart and dxBarGauge 
    indicatingSet: ['#90ba58', '#eeba69', '#a37182'], // for dxCircularGauge and dxLinearGauge
    gradientSet: ['#78b6d9', '#eeba69'] // for dxVectorMap
};
DevExpress.viz.core.registerPalette('myCustomPalette', myPalette);

Note that different palettes apply to different widgets. Simple set is used to color chart series in dxChart and dxPieChart and bars in dxBarGauge. Indicating set is used to color ranges in dxCircularGauge and dxLinearGauge. Gradient set is used to color map areas in dxVectorMap.

To use the registered palette, assign the palette name to the palette option of the required widgets.

Obtain a Registered Palette

To obtain the color sets of a registered palette, use the DevExpress.viz.core.getPalette(paletteName) method. This method returns an object of the following type.

JavaScript
{
    simpleSet: ['#60a69f', '#78b6d9', ...], // palette colors for dxChart, dxPieChart and dxBarGauge 
    indicatingSet: ['#90ba58', '#eeba69', ...], // palette colors for dxCircularGauge and dxLinearGauge
    gradientSet: ['#78b6d9', '#eeba69'] // palette colors for dxVectorMap
};

To get an array of colors of a specific set, call the same method with two arguments. For example, to get the colors of the simple set, use the following code.

JavaScript
var simpleSetColors = DevExpress.viz.core.getPalette(paletteName, { type: 'simpleSet' });

Apply a Palette to All Widgets

You can apply a predefined palette to all widgets at once. Use the DevExpress.viz.core.currentPalette(paletteName) method to do this.

JavaScript
DevExpress.viz.core.currentPalette('Soft Pastel');

The registered custom palettes can be applied using this method as well.