Skip to main content
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.
ModeisEditableshowTooltipsshowHoverEffectsanimateTransitionsisExplorable
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

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 };

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.
BeforeAfter
<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.
BeforeAfter
<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.
BeforeAfter
<Graph isEditable={false} /><Graph mode="readonly" />
<Graph isEditable={true} /><Graph mode="editor" />