Graph

Graph is the component that renders the chart. It must be used inside a GraphProvider.

Basic usage

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

<GraphProvider config={config}>
  <Graph />
</GraphProvider>;

Props

All props are optional.

Mode

mode

'readonly' | 'editor' | 'static'

Shortcut prop for setting sensible defaults for the interactivity and behavior of the graph for common use cases.

Mode	`isEditable`	`showTooltips`	`showHoverEffects`	`animateTransitions`	`isExplorable`
`readonly`	✗	✓	✓	✓	✓
`editor`	✓	✓	✓	✓	✓
`static`	✗	✗	✗	✗	✗

When no mode is provided, the graph behaves like readonly by default.

// Readonly graph with full interactivity (default)
<Graph mode="readonly" />

// Editable graph
<Graph mode="editor" />

// Useful for thumbnails or exports
<Graph mode="static" />

Sizing

sizing

GraphSizing

Controls how the graph responds to its container size. - mode: 'fixed' - graph has a fixed width and height (default) - mode: 'responsive' - graph automatically resizes to fit its parent container - mode: 'keepAspectRatio'

graph scales to fit container while maintaining aspect ratio (requires either intrinsic dimensions or aspect ratio)

// Fixed sizing: specific dimensions
<Graph sizing={{ mode: 'fixed', width: 800, height: 600 }} />

// Responsive sizing: fills container
<Graph sizing={{ mode: 'responsive' }} />

// Keep aspect ratio: with intrinsic dimensions
<Graph sizing={{ mode: 'keepAspectRatio', intrinsicWidth: 800, intrinsicHeight: 600 }} />

// Keep aspect ratio: with intrinsic width and aspect ratio
<Graph sizing={{ mode: 'keepAspectRatio', intrinsicWidth: 800, aspectRatio: 1.5 }} />

// Keep aspect ratio: with intrinsic height and aspect ratio
<Graph sizing={{ mode: 'keepAspectRatio', intrinsicHeight: 600, aspectRatio: 1.5 }} />

Error handling

onError

function

Callback invoked when the graph encounters an error. Useful for logging or analytics.Signature: (info: { error: Error, errorInfo: React.ErrorInfo }) => void

errorFallback

React.ComponentType<{ error: Error }>

Component to render when the graph encounters an error. Receives the error as a prop.

<Graph
  onError={({ error }) => {
    console.error('Chart error:', error);
  }}
  errorFallback={({ error }) => <div>Something went wrong: {error.message}</div>}
/>

Callbacks

onResize

function

Callback invoked when the chart container is resized.Signature: (entries: ResizeObserverEntry[]) => void

<Graph
  onResize={(entries) => {
    console.log('Chart resized:', entries[0].contentRect);
  }}
/>

Custom rendering

hasBorder

boolean

default:"true"

If false, no border will be shown around the graph (this overrides the border styling set in the GraphConfig).

// Without border
<Graph hasBorder={false} />

footerContent

React.ReactNode

Custom content to display in the chart footer area.

<Graph footerContent={<div>Custom footer content</div>} />

renderTitle

function

Custom render function for the chart title area.Signature:

(props: { isEditable: boolean, titleDocument: JSONContent, onChange: (newTitle: JSONContent) => void }) => React.ReactNode

<Graph renderTitle={({ titleDocument, onChange }) => <CustomTitleEditor value={titleDocument} onChange={onChange} />} />

ref

React.Ref<HTMLDivElement>

Ref to the graph container element.

const graphRef = useRef<HTMLDivElement>(null);

<Graph ref={graphRef} />;

Advanced props

These props allow fine-grained control over individual behaviors. In most cases, you should use the mode prop instead.

Precedence order: explicit props → mode → GraphConfig settings → defaults. For example, showTooltips={false} will override both the mode setting and appearance.showTooltips in your config.

isEditable

boolean

default:"false"

Whether the graph is editable. Changes are handled by the GraphProvider.onChange handler.

showTooltips

boolean

default:"true"

Whether to show tooltips on hover. Overrides the appearance.showTooltips setting in GraphConfig.

showHoverEffects

boolean

default:"true"

Whether to show hover effects (line markers, bar highlighting, etc.).

animateTransitions

boolean

default:"true"

Whether to animate the graph on initial render and when data changes. Overrides the appearance.animateTransitions setting in GraphConfig.

isExplorable

boolean

default:"true"

Whether to allow transient, in-memory interactions for exploring the data. These interactions do not modify the GraphConfig. Currently supports: - Legend toggling — click legend items to temporarily hide/show series

// Fine-grained control example: editable with no animations
<Graph
  isEditable={true}
  animateTransitions={false}
/>

// Readonly mode but without tooltips
<Graph
  mode="readonly"
  showTooltips={false}
/>

Examples

Responsive dashboard chart

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

const config: GraphConfig = {
  data: {
    columns: [
      { key: 'month', label: 'Month' },
      { key: 'revenue', label: 'Revenue' },
    ],
    rows: [
      { month: 'Jan', revenue: 12000 },
      { month: 'Feb', revenue: 15000 },
      { month: 'Mar', revenue: 18000 },
    ],
  },
  type: 'column',
};

function DashboardChart() {
  return (
    <div style={{ width: '100%', height: 400 }}>
      <GraphProvider config={config}>
        <Graph mode="readonly" sizing={{ mode: 'responsive' }} />
      </GraphProvider>
    </div>
  );
}

Exportable chart with fixed dimensions

function ExportableChart({ config }: { config: GraphConfig }) {
  const graphRef = useRef<HTMLDivElement>(null);

  const handleExport = async () => {
    // Use graphRef.current to capture the chart as an image
  };

  return (
    <GraphProvider config={config}>
      <Graph ref={graphRef} mode="static" sizing={{ mode: 'fixed', width: 1200, height: 800 }} hasBorder={false} />
    </GraphProvider>
  );
}

Type definitions

GraphSizing

type GraphSizing = 
  | { mode: 'responsive' }
  | { mode: 'fixed'; width: number; height: number }
  | { mode: 'keepAspectRatio'; intrinsicWidth: number; intrinsicHeight: number }
  | { mode: 'keepAspectRatio'; intrinsicWidth: number; aspectRatio: number }
  | { mode: 'keepAspectRatio'; intrinsicHeight: number; aspectRatio: number };

GraphTitleRenderProps

interface GraphTitleRenderProps {
  /** Whether the graph is in edit mode */
  isEditable: boolean;
  /** The current title as a TipTap JSONContent document */
  titleDocument: JSONContent;
  /** Callback to update the title */
  onChange: (newTitle: JSONContent) => void;
}

Migrating from older versions

`isInteractive` prop (removed in `0.0.62`)

The isInteractive prop has been replaced by the mode prop.

Before	After
`<Graph />` (no prop)	`<Graph />` — no changes needed
`<Graph isInteractive={true} />`	`<Graph />` — remove the prop
`<Graph isInteractive={false} />`	`<Graph mode="static" />`

`disableAnimation` prop (removed in `0.0.62`)

The disableAnimation prop has been replaced by the mode prop or animateTransitions.

Before	After
`<Graph />` (no prop)	`<Graph />` — no changes needed
`<Graph disableAnimation={false} />`	`<Graph />` — remove the prop
`<Graph disableAnimation={true} />`	`<Graph mode="static" />` or `<Graph animateTransitions={false} />`

`isEditable` prop

The isEditable prop is still supported but we recommend using mode instead for clarity.

Before	After
`<Graph isEditable={false} />`	`<Graph mode="readonly" />`
`<Graph isEditable={true} />`	`<Graph mode="editor" />`

GraphProvider - State management and configuration
Error Handling - Error handling patterns

Get Started

Graph types

Customisation

Configuration

Editor

Advanced

Reference

Basic usage

Props

Mode

Sizing

Error handling

Callbacks

Custom rendering

Advanced props

Examples

Responsive dashboard chart

Exportable chart with fixed dimensions

Type definitions

Migrating from older versions

`isInteractive` prop (removed in `0.0.62`)

`disableAnimation` prop (removed in `0.0.62`)

`isEditable` prop

​Basic usage

​Props

​Mode

​Sizing

​Error handling

​Callbacks

​Custom rendering

​Advanced props

​Examples

​Responsive dashboard chart

​Exportable chart with fixed dimensions

​Type definitions

​Migrating from older versions

​isInteractive prop (removed in 0.0.62)

​disableAnimation prop (removed in 0.0.62)

​isEditable prop

​Related

Basic usage

Props

Mode

Sizing

Error handling

Callbacks

Custom rendering

Advanced props

Examples

Responsive dashboard chart

Exportable chart with fixed dimensions

Type definitions

Migrating from older versions

`isInteractive` prop (removed in `0.0.62`)

`disableAnimation` prop (removed in `0.0.62`)

`isEditable` prop

Related