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.

import type { GraphConfig } from '@graphysdk/core';

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

Schema structure

Required properties

Data

required

Data to visualise. Contains columns and rows. See data structure for detailed documentation.

Optional properties

Type

Graph type to render. Defaults to 'column' if not specified. See graph types for all available types.

Options

Chart type-specific options (line thickness, smooth lines, bar sorting, etc.). See type options for details.

Axes

Axis configuration for x, y and secondary y axes. See axes configuration for details.

Legend

Legend position and visibility. See legend configuration for details.

Appearance

Visual styling including colors, borders, backgrounds, text styles and number formatting. See appearance configuration for details.

GraphThemeOverrides

Theme-level customization. Overrides specific theme values like graphBackground, textColor, etc. See GraphTheme schema for available properties.

Content

Text content for title, subtitle, caption, data source, and the optional Made with Graphy provenance mark. See content configuration for details — notably isBrandMarkHidden (hidden by default; set false to opt in).

HeadlineNumbers

Summary metrics displayed prominently on the chart. See headline numbers for details.

DataLabels

Configuration for value labels displayed on chart elements. See data labels for details.

Annotations

Visual annotations layered on top of the chart (stickers, tooltips, highlights, text, arrows, shapes). See annotations for details.

ReferenceLines

Goal lines, trendlines and average lines. See reference lines for details.

Complete example

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',
    },
    // Opt in to the Made with Graphy badge (hidden by default at low level).
    isBrandMarkHidden: false,
  },

  // 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:

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:

import { GraphProvider, Graph } from '@graphysdk/core';

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

Get Started

Graph types

Customisation

Configuration

Editor

Advanced

Reference

Overview

Schema structure

Required properties

Optional properties

Complete example

Type definitions

Using with GraphProvider

​Overview

​Schema structure

​Required properties

​Optional properties

​Complete example

​Type definitions

​Using with GraphProvider

Overview

Schema structure

Required properties

Optional properties

Complete example

Type definitions

Using with GraphProvider