Configuration

Premium

Updated on Nov 5, 2026

The Chart is a highly customizable component that you can configure in multiple ways to suit different development scenarios. Configure the Chart with two primary approaches for its appearance and behavior, or combine them for maximum flexibility.

You can configure the Chart with:

• Configuration objects—Pass plain objects to Chart properties for a compact, data-driven representation.
• Built-in components—Use React components like <ChartSeries> as nested tags in the <Chart> component.

The following table compares the two configuration approaches to help you choose the right method for your scenario.

Aspect	Configuration objects	Built-in components
Pros	Type validation in TypeScript projects Serialize settings to and from JSON	Configure chart settings in JSX
Cons	Configuration is separate from rendering logic	Serialize full configuration with extra work Manage large configurations in JSX
When to use	Your project uses TypeScript You need to persist and restore user settings You need to load chart settings from a store	You want to keep settings organized in the JSX

Use Configuration Objects

Configure the Chart by passing ChartOptions to its options prop.

tsx

import { Chart, ChartOptions } from '@progress/kendo-react-charts';

const chartOptions: ChartOptions = {
    title: { text: 'Units sold' },
    categoryAxis: [{ categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] }],
    series: [{ name: 'Apples', type: 'line', data: [1, 2, 3, 4, 5, 6] }]
};

const ChartContainer = () => <Chart options={chartOptions} />;

The following example demonstrates a comprehensive configuration with objects. This chart displays regional sales performance with complete styling and formatting.

Example

View Source

Loading ...

This approach provides a compact, data-driven representation. It is ideal when you load chart settings from a store or when you need to persist and restore them.

Advantages of configuration objects include:

• Large configurations are easier to manage in TypeScript than in JSX.
• The configuration is strongly typed and can be validated at compile time.
• Configuration can be saved to and loaded from JSON format.
  • Some exceptions apply, such as functions, which cannot be serialized to JSON.
• Settings can be loaded from external sources like databases or APIs.
• Chart state can be saved and restored across sessions.

Use Built-in Components

Built-in components enable you to configure the Chart declaratively with React components nested within the <Chart> component.

tsx

const ChartContainer = () => (
    <Chart>
        <ChartTitle text="Units sold" />
        <ChartCategoryAxis>
            <ChartCategoryAxisItem categories={['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']} />
        </ChartCategoryAxis>
        <ChartSeries>
            <ChartSeriesItem name="Apples" type="line" data={[1, 2, 3, 4, 5, 6]} />
        </ChartSeries>
    </Chart>
);

The following example demonstrates a comprehensive configuration with built-in components. This chart displays regional sales performance with the same styling and formatting as the configuration objects example.

Example

View Source

Loading ...

This approach provides a declarative representation that is ideal for scenarios where template visibility and IDE support are important.

Advantages of built-in components include:

• Configuration is visible and organized in the template.

Mixed Configuration

Mixed configuration enables you to combine configuration objects and built-in components in the same Chart, balancing compact representation with declarative clarity.

Both configuration objects and built-in nested components update the same internal store. When you configure a property with both approaches, the component takes precedence over the configuration object—this precedence is preserved even after the options prop changes.

tsx

import {
    ChartOptions,
    Chart,
    ChartCategoryAxis,
    ChartCategoryAxisItem,
    ChartSeries,
    ChartSeriesItem
} from '@progress/kendo-react-charts';

const chartOptions: ChartOptions = {
    title: { text: 'Sample Chart' },
    legend: { position: 'top' }
};

const ChartContainer = () => (
    <Chart options={chartOptions}>
        <ChartCategoryAxis>
            <ChartCategoryAxisItem categories={['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']} />
        </ChartCategoryAxis>
        <ChartSeries>
            <ChartSeriesItem name="Apples" type="line" data={[1, 2, 3, 4, 5, 6]} />
        </ChartSeries>
    </Chart>
);

The following example demonstrates combining both approaches effectively. Global settings like title and legend use configuration objects, while series configuration uses built-in components.

Example

View Source

Loading ...

This approach is ideal when you want to use configuration objects for global settings (title, legend, tooltip) and components for series-specific settings that benefit from template flexibility.

Advantages of mixed configuration include:

• Balance between compactness and declarative clarity.
• Use configuration objects for settings that are easier to manage in TypeScript.
• Use built-in components for settings that benefit from template visibility and JSX features.

Persist and Restore Settings

You can persist the Chart configuration by serializing the configuration objects to JSON. Later, restore them by parsing the JSON back into JavaScript objects. This is useful when you save user preferences or persist chart settings across sessions.

The following example demonstrates how to persist and restore the Chart configuration.

Example

View Source

Loading ...

This approach is ideal when you need to:

• Save user customizations across sessions.
• Share configurations between different charts or applications.
• Persist Chart settings across user sessions.

Considerations for Persisting and Restoring Settings

When you replace the options prop with a new object, the Chart treats the new object as a full replacement rather than merging it with the previous one.

• Properties that existed in the previous options object but are missing from the new one are cleared.
• Properties configured through a built-in component keep displaying the component's value, regardless of what the new options object contains for that same property.

In the example below, the rendered series is always "Oranges", no matter what series data the options state holds, both on the initial render and after any later call to setOptions.

tsx

const ChartContainer = () => {
    const [options, setOptions] = React.useState<ChartOptions>({
        series: [{ name: 'Apples', data: [1, 2, 3] }]
    });

    return (
        <Chart options={options}>
            <ChartSeries>
                <ChartSeriesItem name="Oranges" data={[4, 5, 6]} />
            </ChartSeries>
        </Chart>
    );
};

Suggested Links

• React Charts Homepage
• API Reference of the React Charts
• Data Binding