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

# GraphConfig

## Overview

`GraphConfig` is the main configuration object for creating and customising graphs in the Graphy SDK. It combines data, visual styling, text content and interactive features into a single, strongly-typed configuration.

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

const config: GraphConfig = {
  data: {
    /* ... */
  },
  type: 'column',
  // ... other properties
};
```

## Schema structure

### Required properties

<ParamField path="data" type="Data" required>
  Data to visualise. Contains columns and rows. See [data structure](/sdk/core/data-structure) for detailed documentation.
</ParamField>

### Optional properties

<ParamField path="type" type="Type" optional>
  Graph type to render. Defaults to `'column'` if not specified. See [graph types](/sdk/graph-types/index) for all available
  types.
</ParamField>

<ParamField path="options" type="Options" optional>
  Chart type-specific options (line thickness, smooth lines, bar sorting, etc.). See [type
  options](/sdk/config/type-options) for details.
</ParamField>

<ParamField path="axes" type="Axes" optional>
  Axis configuration for x, y and secondary y axes. See [axes configuration](/sdk/config/axes) for details.
</ParamField>

<ParamField path="legend" type="Legend" optional>
  Legend position and visibility. See [legend configuration](/sdk/config/legend) for details.
</ParamField>

<ParamField path="appearance" type="Appearance" optional>
  Visual styling including colors, borders, backgrounds, text styles and number formatting. See [appearance
  configuration](/sdk/config/appearance) for details.
</ParamField>

<ParamField path="themeOverrides" type="GraphThemeOverrides" optional>
  Theme-level customization. Overrides specific theme values like `graphBackground`, `textColor`, etc. See [GraphTheme
  schema](/sdk/reference/graph-theme) for available properties.
</ParamField>

<ParamField path="content" type="Content" optional>
  Text content for title, subtitle, caption and data source. See [content configuration](/sdk/config/content) for details.
</ParamField>

<ParamField path="headlineNumbers" type="HeadlineNumbers" optional>
  Summary metrics displayed prominently on the chart. See [headline numbers](/sdk/config/headline-numbers) for details.
</ParamField>

<ParamField path="dataLabels" type="DataLabels" optional>
  Configuration for value labels displayed on chart elements. See [data labels](/sdk/config/data-labels) for details.
</ParamField>

<ParamField path="annotations" type="Annotations" optional>
  Visual annotations layered on top of the chart (stickers, tooltips, highlights, text, arrows, shapes). See
  [annotations](/sdk/config/annotations) for details.
</ParamField>

<ParamField path="referenceLines" type="ReferenceLines" optional>
  Goal lines, trendlines and average lines. See [reference lines](/sdk/config/reference-lines) for details.
</ParamField>

## Complete example

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

const config: GraphConfig = {
  // Data (required)
  data: {
    columns: [
      { key: 'quarter', label: 'Quarter' },
      { key: 'revenue', label: 'Revenue' },
      { key: 'profit', label: 'Profit' },
    ],
    rows: [
      { quarter: 'Q1', revenue: 100000, profit: 25000 },
      { quarter: 'Q2', revenue: 120000, profit: 30000 },
      { quarter: 'Q3', revenue: 135000, profit: 35000 },
      { quarter: 'Q4', revenue: 150000, profit: 42000 },
    ],
  },

  // Graph type
  type: 'line',

  // Type-specific options
  options: {
    isSmoothLine: true,
    showPoints: true,
    lineThickness: 2,
  },

  // Axes configuration
  axes: {
    x: {
      label: 'Fiscal quarter',
    },
    y: {
      label: 'Amount (£)',
      min: 0,
    },
    showGridLines: true,
  },

  // Legend
  legend: {
    position: 'right',
  },

  // Appearance
  appearance: {
    paletteId: 'corporate',
    seriesStyles: {
      series1: {
        customColor: '#1e40af',
        lineStyle: 'solid',
      },
      series2: {
        customColor: '#059669',
        lineStyle: 'solid',
      },
    },
    border: {
      style: 'tinted',
      color: '#1e40af',
      width: 8,
    },
    hasRoundedCorners: true,
    textScale: 1,
    numberFormat: {
      decimalPlaces: 0,
      abbreviation: 'k',
    },
    showTooltips: true,
    animateTransitions: true,
  },

  // Text content
  content: {
    title: 'Quarterly financial performance',
    subtitle: 'FY 2024',
    caption: 'All figures are preliminary',
    source: {
      label: 'Finance department',
      url: 'https://company.com/finance',
    },
  },

  // Headline numbers
  headlineNumbers: {
    show: 'current',
    compareWith: 'previous',
    size: 'large',
  },

  // Data labels
  dataLabels: {
    showDataLabels: false,
  },

  // Reference lines
  referenceLines: {
    goalLine: {
      target: 140000,
      label: 'Target',
    },
    trendline: 'linear',
  },
};
```

## Type definitions

The `GraphConfig` type is defined using Zod for runtime validation:

```tsx theme={null}
export const GraphConfig = z.object({
  data: Data,
  type: Type.optional(),
  options: Options.optional(),
  axes: Axes.optional(),
  legend: Legend.optional(),
  appearance: Appearance.optional(),
  themeOverrides: GraphThemeOverrides.optional(),
  content: Content.optional(),
  headlineNumbers: HeadlineNumbers.optional(),
  dataLabels: DataLabels.optional(),
  annotations: Annotations.optional(),
  referenceLines: ReferenceLines.optional(),
});

export type GraphConfig = z.infer<typeof GraphConfig>;
```

## Using with GraphProvider

Pass your config to `GraphProvider`:

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

function App() {
  return (
    <GraphProvider config={config}>
      <Graph />
    </GraphProvider>
  );
}
```