Skip to main content

​
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
Data
required
Data to visualise. Contains columns and rows.See data structure for detailed documentation.

​
Optional properties

​
type
Type
Graph type to render. Defaults to 'column' if not specified.See graph types for all available types.
​
options
Options
Chart type-specific options (line thickness, smooth lines, bar sorting, etc.).See type options for details.
​
axes
Axes
Axis configuration for x, y and secondary y axes.See axes configuration for details.
​
legend
Legend
Legend position and visibility.See legend configuration for details.
​
appearance
Appearance
Visual styling including colors, borders, backgrounds, text styles and number formatting.See appearance configuration for details.
​
themeOverrides
GraphThemeOverrides
Theme-level customization. Overrides specific theme values like graphBackground, textColor, etc.See GraphTheme schema for available properties.
​
content
Content
Text content for title, subtitle, caption and data source.See content configuration for details.
​
headlineNumbers
HeadlineNumbers
Summary metrics displayed prominently on the chart.See headline numbers for details.
​
dataLabels
DataLabels
Configuration for value labels displayed on chart elements.See data labels for details.
​
annotations
Annotations
Visual annotations layered on top of the chart (stickers, tooltips, highlights, text, arrows, shapes).See annotations for details.
​
referenceLines
ReferenceLines
Goal lines, trendlines and average lines.See reference lines for details.
​
_metadata
Metadata
Internal metadata. This is managed automatically and should not be set manually.

​
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: {
    palette: {
      id: 'corporate',
      name: 'Corporate',
      colors: [
        { id: '1', hex: '#1e40af', name: 'Blue' },
        { id: '2', hex: '#059669', name: 'Green' }
      ]
    },
    seriesStyles: {
      'revenue': {
        customColor: '#1e40af',
        lineStyle: 'solid'
      },
      'profit': {
        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: 
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(),
  _metadata: Metadata.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>
  );
}

​
Validation

The GraphConfig schema includes runtime validation via Zod. Invalid configurations will throw validation errors with helpful messages: 
// This will throw a validation error
const invalidConfig = {
  data: {
    columns: [],  // Error: columns array must not be empty
    rows: []
  }
};

​
Migration from old schema

If you’re migrating from the old schema, the main differences are:
Old schemaNew schema
data: RawData[]data: { columns: Column[], rows: Row[] }
datasetConfigMerged into data.columns
visualizationConfigSplit into type and options
customAppearanceConfigRenamed to appearance
titleDocument, captionMoved to content.title, content.caption
sourceLabel, sourceUrlMoved to content.source
See individual configuration pages for migration details.