# Chart Config

> Define labels, theme colors, and icons for each chart series.

Source: https://www.honestui.com/docs/charts/chart-config

Every Honest UI chart accepts a `config` prop. Pass it a `ChartConfig` object that maps data keys to visible labels, theme colors, and optional icons used by tooltips and legends.

## Structure [#structure]

```tsx
import { type ChartConfig } from "honestui/charts";

const chartConfig = {
  harvested: {
    label: "Harvested",
    icon: WheatIcon,
    colors: {
      light: ["#047857"],
      dark: ["#10b981"],
    },
  },
  packed: {
    label: "Packed",
    icon: PackageCheckIcon,
    colors: {
      light: ["#be123c"],
      dark: ["#f43f5e"],
    },
  },
} satisfies ChartConfig;
```

Each key, such as `harvested` or `packed`, must match a data key used by the corresponding series. The object has this type:

```tsx
type ChartConfig = Record<
  string,
  {
    label?: React.ReactNode;
    icon?: React.ComponentType;
    colors?: {
      light?: string[];
      dark?: string[];
    };
  }
>;
```

## Properties [#properties]

### label [#label]

The name shown in tooltips and legends. Use a concise label that makes sense outside the chart.

```tsx
const chartConfig = {
  harvested: {
    label: "Harvested", // [!code highlight]
    // ...
  },
} satisfies ChartConfig;
```

### colors [#colors]

Theme-aware color arrays. Provide at least one theme key (`light` or `dark`); each holds an array of CSS color strings.

Use one color per theme for a solid fill:

```tsx
colors: {
  light: ["#047857"],
  dark: ["#10b981"],
}
```

Use multiple colors to create a gradient. The chart distributes the stops across the rendered series:

```tsx
colors: {
  light: ["#a855f7", "#6366f1", "#3b82f6"],
  dark: ["#f43f5e", "#ec4899", "#a855f7", "#6366f1", "#3b82f6"],
}
```

Light and dark themes may define different numbers of color stops. The chart uses the larger count when distributing them.

### icon [#icon]

An optional React component that replaces the default color indicator in the tooltip and legend. Icons can reinforce a distinction, but visible labels must still identify each series.

```tsx
import { PackageCheck, Wheat } from "honestui/icons";

const chartConfig = {
  harvested: {
    label: "Harvested",
    icon: Wheat, // [!code highlight] [!code word:Wheat]
    colors: { light: ["#047857"], dark: ["#10b981"] },
  },
  packed: {
    label: "Packed",
    icon: PackageCheck, // [!code highlight] [!code word:PackageCheck]
    colors: { light: ["#be123c"], dark: ["#f43f5e"] },
  },
} satisfies ChartConfig;
```

The icon replaces the color indicator in tooltips and legends. Tooltips render it at `h-2.5 w-2.5`; legends render it at `h-3 w-3`.

## How Colors Work [#how-colors-work]

The chart config generates CSS custom properties scoped to each chart instance. A key `harvested` with colors `["#a855f7", "#6366f1"]` produces:

```css
--color-harvested-0: #a855f7;
--color-harvested-1: #6366f1;
```

Chart components, tooltips, and legends read these variables. When the application changes between the supported light and dark themes, the chart reads the corresponding values.

### Color Distribution [#color-distribution]

When you provide fewer colors than segments need, they're **evenly distributed** across slots:

* 2 colors for 4 slots: `[red, red, pink, pink]`
* 3 colors for 4 slots: `[red, pink, blue, blue]`

Use enough stops to communicate the intended progression, then verify the result with representative data in both themes.

## Runtime Validation [#runtime-validation]

The config is validated at runtime. An empty `colors` object, or one without a valid theme key, throws a clear error:

```plaintext
[Honest UI] Invalid chart config for "harvested": colors object must
have at least one theme key (light, dark). Received empty object or
invalid keys.
```

## Examples [#examples]

### Default (Labels + Colors) [#default-labels--colors]

Labels and theme-aware colors. The label shows in the tooltip and legend; the colors control the fill.

<ComponentPreview title="Basic chart config" name="ex-chart-config-default-bar-chart" />

### With Icons [#with-icons]

Pass an `icon` component per entry to replace the default color indicator in the tooltip and legend.

<ComponentPreview title="Chart config with icons" name="ex-chart-config-icons-bar-chart" />

### Gradient Colors [#gradient-colors]

Pass multiple colors per theme for gradient fills. Each array value is a stop distributed across the chart elements.

<ComponentPreview title="Gradient colors" name="ex-gradient-colors-bar-chart" />

## API Reference [#api-reference]


  ### `label`

type: `React.ReactNode`

Name for the data series, shown in tooltips and legends.

  ### `colors`

type: `{ light?: string[]; dark?: string[] }`

Theme-aware colors. Include at least one theme key (`light` or `dark`), each mapping to an array of CSS color strings. One color is a solid fill; multiple create a gradient.

  ### `icon`

type: `React.ComponentType`

Optional React component rendered in place of the default color indicator in tooltips and legends.