Skip to main content
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 — the right tool for the majority of cases. Adjust colours, typography, and spacing through a structured token system without touching any markup.
  2. Config — targeted appearance and behaviour overrides for specific chart types or elements.
  3. 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: 
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: 
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. 
const config: GraphConfig = {
  data: { ... },
  themeOverrides: {
    graphBackground: '#1e293b',
    textPrimary: '#f8fafc',
    gridLineColor: '#334155',
  },
};

<Graph config={config} />
For a full reference of available tokens see the GraphTheme 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 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 
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 
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 
<EditorProvider
  components={{
    Switch: CustomSwitch,
  }}
/>
For a full list of components that can be customised see the EditorComponentRegistry API reference.