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 at least one predefined theme for each supported platform. The list of supported platforms and themes is included below.

  • Android

    • 'android5.light'
  • iOS

    • 'ios7.default'
  • Windows 8

    • 'win8.black'
    • 'win8.white'

DevExtreme also provides the platform-agnostic theme set called Generic, which includes the 'generic.light' and 'generic.dark' themes.

Each DevExtreme visualization widget has a theme configuration option that allows you to set a theme. It is also convenient to apply a theme for the entire page with several DevExtreme widgets. To do this, use the DevExpress.viz.currentTheme method passing the name of the required theme as a parameter.

JavaScript
DevExpress.viz.currentTheme('android5.light');

If you are creating a cross-platform application, you can determine on which platform the page is currently running. Use the DevExpress.devices.current() method. The method's return value can be used for auto-specifying the theme.

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

In addition to the current device, 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.currentTheme(DevExpress.devices.current(), 'light');

If you do not set the required theme, the "generic.light" 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

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.registerTheme(myTheme,'generic.light');

Apply a Custom Theme

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

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

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

JavaScript
var chartOptions = {
    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
  • dxPolarChart
  • 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
var chartOptions = {
    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
var chartOptions = {
    series: [{
        color: 'red'
        //...
    }, {...}, ...]
};

var gaugeOptions = {
    rangeContainer: {
        ranges: [{
            color: 'red'
            //...
        }, {...}, ...]
    }
};

var vectorMapOptions = {
    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
var chartOptions = {
    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.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.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
};

Apply a Palette to All Widgets

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

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

If you call this method at runtime, re-render widgets on your page to make palette change visible.