# Configuration

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](https://www.telerik.com/kendo-react-ui/components/charts/chart/configuration#use-configuration-objects)—Pass plain objects to Chart properties for a compact, data-driven representation.
* [Built-in components](https://www.telerik.com/kendo-react-ui/components/charts/chart/configuration#use-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.

<table>
    <thead>
        <tr>
            <th style="width: 110px;">Aspect</th>
            <th>Configuration objects</th>
            <th>Built-in components</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><strong>Pros</strong></td>
            <td>
                <ul>
                    <li>Type validation in TypeScript projects</li>
                    <li>Serialize settings to and from JSON</li>
                </ul>
            </td>
            <td>
                <ul>
                    <li>Configure chart settings in JSX</li>
                </ul>
            </td>
        </tr>
        <tr>
            <td><strong>Cons</strong></td>
            <td>
                <ul>
                    <li>Configuration is separate from rendering logic</li>
                </ul>
            </td>
            <td>
                <ul>
                    <li>Serialize full configuration with extra work</li>
                    <li>Manage large configurations in JSX</li>
                </ul>
            </td>
        </tr>
        <tr>
            <td><strong>When to use</strong></td>
            <td>
                <ul>
                    <li>Your project uses TypeScript</li>
                    <li>You need to persist and restore user settings</li>
                    <li>You need to load chart settings from a store</li>
                </ul>
            </td>
            <td>
                <ul>
                    <li>You want to keep settings organized in the JSX</li>
               </ul>
            </td>
        </tr>
    </tbody>
</table>

## Use Configuration Objects

Configure the Chart by passing `ChartOptions` to its [options prop](https://www.telerik.com/kendo-react-ui/components/charts/api/chartprops#options).

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

[Demo Source](https://demos.telerik.com/kendo-react-ui/charts/chart/configuration/options-comprehensive/source.txt)

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](https://www.telerik.com/kendo-react-ui/components/charts/chart/configuration#use-configuration-objects).

[Demo Source](https://demos.telerik.com/kendo-react-ui/charts/chart/configuration/components-comprehensive/source.txt)

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](https://www.telerik.com/kendo-react-ui/components/charts/chart/configuration#use-configuration-objects) and [built-in components](https://www.telerik.com/kendo-react-ui/components/charts/chart/configuration#use-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.

[Demo Source](https://demos.telerik.com/kendo-react-ui/charts/chart/configuration/mixed/source.txt)

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.

[Demo Source](https://demos.telerik.com/kendo-react-ui/charts/chart/configuration/persist-restore/source.txt)

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](https://www.telerik.com/kendo-react-ui/charts)
* [API Reference of the React Charts](https://www.telerik.com/kendo-react-ui/components/charts/api)
* [Data Binding](https://www.telerik.com/kendo-react-ui/components/charts/chart/data-binding)