> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphProvider

`GraphProvider` is the root component that wraps your graphs and provides configuration, theming and state management.

## Basic usage

```tsx theme={null}
import { useState } from 'react';
import { GraphProvider, Graph } from '@graphysdk/core';
import type { GraphConfig } from '@graphysdk/core';

function MyGraph() {
  const [config, setConfig] = useState<GraphConfig>();

  return (
    <GraphProvider
      config={config}
      onChange={(update) => {
        setConfig((currentValues) => ({ ...currentValues, ...update }));
      }}
    >
      <Graph />
    </GraphProvider>
  );
}
```

## Props

<ParamField path="children" type="React.ReactNode" optional>
  Components to render within the provider. Typically includes `Graph` and optionally editor components.
</ParamField>

<ParamField path="config" type="GraphConfig" optional>
  The graph configuration object. See [GraphConfig schema](/sdk/reference/graph-config) for all available options.
</ParamField>

```tsx theme={null}
const config: GraphConfig = {
  data: {
    columns: [
      { key: 'month', label: 'Month' },
      { key: 'sales', label: 'Sales' },
    ],
    rows: [
      { month: 'Jan', sales: 1000 },
      { month: 'Feb', sales: 1200 },
    ],
  },
  type: 'column',
  content: {
    title: 'Monthly sales',
  },
};

<GraphProvider config={config}>
  <Graph />
</GraphProvider>;
```

<ParamField path="onChange" type="function" optional>
  Callback invoked when the graph configuration changes (typically from editor interactions).

  **Signature:** `(changedValues: Partial<GraphConfig>, currentValues: GraphConfig) => void`

  * `changedValues` - Only the properties that changed
  * `currentValues` - The complete updated configuration
</ParamField>

```tsx theme={null}
<GraphProvider
  config={config}
  onChange={(changedValues, currentValues) => {
    console.log('Changed:', changedValues);
    console.log('Current:', currentValues);
    setConfig(currentValues);
  }}
>
  <Graph />
</GraphProvider>
```

<ParamField path="theme" type="GraphTheme" optional>
  Custom theme for the graph. See [GraphTheme reference](/sdk/reference/graph-theme) for all available properties. Defaults
  to `graphyLightTheme` if not provided.
</ParamField>

```tsx theme={null}
import { graphyDarkTheme } from '@graphysdk/core';

<GraphProvider theme={graphyDarkTheme}>
  <Graph />
</GraphProvider>;
```

<ParamField path="fontList" type="FontList" optional>
  Array of custom fonts available for use in graphs. Each font definition includes an `id`, `label` and `fontFamily`.
  See [Fonts](/sdk/customisation/graph-fonts) for usage details.
</ParamField>

```tsx theme={null}
const fontList = [
  {
    id: 'custom-serif',
    label: 'Custom Serif',
    fontFamily: 'Garamond, Baskerville, serif',
  },
];

<GraphProvider fontList={fontList}>
  <Graph />
</GraphProvider>;
```

<ParamField path="customPalettes" type="CustomPaletteCatalog" optional>
  Array of custom color palettes available for graphs. Each palette includes an `id`, `name` and array of `colors`. See
  [Custom color palettes](/sdk/customisation/series-colors#custom-palettes) for usage details.
</ParamField>

```tsx theme={null}
const customPalettes = [
  {
    id: 'brand',
    name: 'Brand Palette',
    colors: [
      { id: '1', hex: '#3b82f6', name: 'Blue' },
      { id: '2', hex: '#ef4444', name: 'Red' },
    ],
  },
];

<GraphProvider customPalettes={customPalettes}>
  <Graph />
</GraphProvider>;
```

<ParamField path="uiLocale" type="Locale" optional>
  Locale for UI text (editor labels, buttons, etc.). Accepts `'en-GB'` or `'en-US'`. Defaults to `'en-US'`.
</ParamField>

<ParamField path="formattingLocale" type="Locale" optional>
  Locale for formatting numbers and dates in the UI. Accepts `'en-GB'` or `'en-US'`. Defaults to `'en-US'`.

  <Note>
    This is different from `data._metadata.parsingLocale`, which controls how data is parsed. This prop controls how
    values are displayed in the editor UI.
  </Note>
</ParamField>

```tsx theme={null}
<GraphProvider uiLocale="en-GB" formattingLocale="en-GB">
  <Graph />
</GraphProvider>
```

<ParamField path="canvasColorToVariableName" type="CanvasColorToVariableName" optional>
  Advanced: Maps canvas color IDs to CSS variable names for custom styling.
</ParamField>

<ParamField path="i18nOverrides" type="object" optional>
  Advanced: Override specific translation strings in the UI. Use this to customize text labels in the editor.

  **Type:** `Partial<Record<TranslationKey, OverridePhrase<TranslationKey>>>`
</ParamField>

## Complete example

```tsx theme={null}
import { useState } from 'react';
import { GraphProvider, Graph, graphyDarkTheme } from '@graphysdk/core';
import type { GraphConfig } from '@graphysdk/core';

const fontList = [
  {
    id: 'custom-sans',
    label: 'Custom Sans',
    fontFamily: 'Helvetica Neue, Arial, sans-serif',
  },
];

const customPalettes = [
  {
    id: 'brand',
    name: 'Brand Palette',
    colors: [
      { id: '1', hex: '#3b82f6', name: 'Blue' },
      { id: '2', hex: '#10b981', name: 'Green' },
    ],
  },
];

function MyGraph() {
  const [config, setConfig] = useState<GraphConfig>({
    data: {
      columns: [
        { key: 'category', label: 'Category' },
        { key: 'value', label: 'Value' },
      ],
      rows: [
        { category: 'A', value: 100 },
        { category: 'B', value: 150 },
      ],
    },
    type: 'column',
    appearance: {
      paletteId: 'brand',
      textStyle: {
        body: {
          fontId: 'custom-sans',
        },
      },
    },
  });

  return (
    <GraphProvider
      config={config}
      onChange={(changedValues, currentValues) => {
        setConfig(currentValues);
      }}
      theme={graphyDarkTheme}
      fontList={fontList}
      customPalettes={customPalettes}
      uiLocale="en-GB"
      formattingLocale="en-GB"
    >
      <Graph />
    </GraphProvider>
  );
}
```

## Type definitions

```tsx theme={null}
type Locale = 'en-GB' | 'en-US';

interface GraphProviderProps {
  children?: React.ReactNode;
  config?: GraphConfig;
  onChange?: (changedValues: Partial<GraphConfig>, currentValues: GraphConfig) => void;
  uiLocale?: Locale;
  formattingLocale?: Locale;
  fontList?: FontList;
  customPalettes?: CustomPaletteCatalog;
  canvasColorToVariableName?: CanvasColorToVariableName;
  theme?: GraphTheme;
  i18nOverrides?: Partial<Record<TranslationKey, OverridePhrase<TranslationKey>>>;
}
```

## Related

* [Graph](/sdk/reference/graph) - Chart rendering component
* [EditorProvider](/sdk/reference/editor-provider) - Editor state management