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

# Custom appearance

Graphy is designed to look good out of the box, but we know that a charting library embedded in your product needs to feel like it belongs there. This page explains the layers of customisation available and when to reach for each one.

## Ways to customise

We think about customisation in three tiers, each offering progressively more control:

1. [**Themes**](#themes) — the right tool for the majority of cases. Adjust colours, typography, and spacing through a structured token system without touching any markup.
2. [**Config**](#config) — targeted appearance and behaviour overrides for specific chart types or elements.
3. [**Custom components**](#custom-components) — replace Graphy's internal UI components with your own when you need a completely native feel.

## Themes

The `theme` prop on `GraphProvider` is the primary way to make Graphy match your brand. Themes use a layered token system: **base tokens** define raw values, **semantic tokens** map those values to purpose, and **element tokens** target specific components.

The SDK includes two built-in themes: `graphyLightTheme` (default) and `graphyDarkTheme` which can be extended to match your preffered style.

Override a semantic token to update many elements at once:

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

<GraphProvider
  theme={{
    ...graphyDarkTheme,
    values: {
      ...graphyDarkTheme.values,
      fontSm: 'bold 12px sans-serif',
      raisedBackground: '#FFFFFF',
    },
  }}
/>;
```

Override an element token when you need surgical control over a single component without affecting anything else:

```tsx theme={null}
values: {
  tooltipBackground: '#1A1A2E',
  tooltipHeadingTextColor: '#FFFFFF',
}
```

Individual properties can also be overriden on `GraphConfig`. This can be useful in situations where you want to enable customisation on a per chart basis. With this approach you can simply store the whole `GraphConfig` object after a change, and restore it later without needing to reconstruct the entire theme each time.

```tsx theme={null}
const config: GraphConfig = {
  data: { ... },
  themeOverrides: {
    graphBackground: '#1e293b',
    textPrimary: '#f8fafc',
    gridLineColor: '#334155',
  },
};

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

For a full reference of available tokens see the [`GraphTheme`](/sdk/reference/graph-theme) API reference.

## Config

The `GraphConfig` object is the primary way to control the appearance and behaviour of individual charts. Where themes set the visual language across your entire application, config is chart-specific.

Config covers a broad surface area. Some of the key properties to be aware of are:

**`axes`**, **`legend`**, and **`options`** handle the structural and chart type specific configuration such as axis labels, tick formatting, line smoothing, bar sorting, legend position, and similar.

**`appearance`** controls visual properties that persist across chart types such as series colours, border style, number formatting and tooltip styles.

**`content`** controls the content and visiblility of additional elements around a chart, such as the title, subtitle and caption.

**`themeOverrides`** allows specific theme tokens to be overridden at the chart level, for cases where a single chart needs to depart from the global theme (a different background colour, for instance) without requiring a separate theme definition.

For a complete reference of all available properties and their types, see the [`GraphConfig`](/sdk/reference/graph-config) API reference.

## Custom components

When themes and props aren't enough, you can replace individual internal components with your own implementations.

### How it works

Graphy defines a typed interface for each overridable component. You implement a component that satisfies that interface, then register it at the provider level.

**1. Graphy's component interface**

```tsx theme={null}
export interface SwitchComponentProps {
  isChecked?: boolean;
  isDisabled?: boolean;
  isInvalid?: boolean;
  onCheckedChange?: (checked: boolean) => void;
  ref?: AnyRef;
}

export type SwitchComponent = React.ComponentType<SwitchComponentProps>;
```

**2. Your custom implementation**

```tsx theme={null}
import type { SwitchComponent } from '@graphysdk/core';
import Switch from '@mui/material/Switch';

// An example implementation using Material UI
const CustomSwitch: SwitchComponent = (props) => {
  return (
    <Switch
      checked={props.isChecked}
      disabled={props.isDisabled}
      color={props.isInvalid ? 'error' : 'primary'}
      onChange={(event) => props.onCheckedChange?.(event.target.checked)}
    />
  );
};
```

**3. Register at the provider level**

```tsx theme={null}
<EditorProvider
  components={{
    Switch: CustomSwitch,
  }}
/>
```

For a full list of components that can be customised see the [`EditorComponentRegistry`](/sdk/reference/editor-component-registry) API reference.