> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Graph

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

## Basic usage

```tsx theme={null}
import { GraphProvider, Graph } from '@graphysdk/core';

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

## Props

All props are optional.

### Mode

<ParamField path="mode" type="'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`   | ✗            | ✗              | ✗                  | ✗                    | ✗              |

  <Tip>
    When no `mode` is provided, the graph behaves like `readonly` by default.
  </Tip>
</ParamField>

```tsx theme={null}
// Readonly graph with full interactivity (default)
<Graph mode="readonly" />

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

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

### Sizing

<ParamField path="sizing" type="GraphSizing" optional>
  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)
</ParamField>

```tsx theme={null}
// 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

<ParamField path="onError" type="function" optional>
  Callback invoked when the graph encounters an error. Useful for logging or analytics.

  **Signature:** `(info: { error: Error, errorInfo: React.ErrorInfo }) => void`
</ParamField>

<ParamField path="errorFallback" type="React.ComponentType<{ error: Error }>" optional>
  Component to render when the graph encounters an error. Receives the error as a prop.
</ParamField>

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

### Callbacks

<ParamField path="onResize" type="function" optional>
  Callback invoked when the chart container is resized.

  **Signature:** `(entries: ResizeObserverEntry[]) => void`
</ParamField>

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

### Custom rendering

<ParamField path="hasBorder" type="boolean" default="true">
  If `false`, no border will be shown around the graph (this overrides the border styling set in the `GraphConfig`).
</ParamField>

```tsx theme={null}
// Without border
<Graph hasBorder={false} />
```

<ParamField path="footerContent" type="React.ReactNode" optional>
  Custom content to display in the chart footer area.
</ParamField>

```tsx theme={null}
<Graph footerContent={<div>Custom footer content</div>} />
```

<ParamField path="renderTitle" type="function" optional>
  Custom render function for the chart title area.

  **Signature:** `(props: { isEditable: boolean, titleDocument: JSONContent, onChange: (newTitle: JSONContent) => void }) => React.ReactNode`
</ParamField>

```tsx theme={null}
<Graph renderTitle={({ titleDocument, onChange }) => <CustomTitleEditor value={titleDocument} onChange={onChange} />} />
```

<ParamField path="ref" type="React.Ref<HTMLDivElement>" optional>
  Ref to the graph container element.
</ParamField>

```tsx theme={null}
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.

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

<ParamField path="isEditable" type="boolean" default="false">
  Whether the graph is editable. Changes are handled by the `GraphProvider.onChange` handler.
</ParamField>

<ParamField path="showTooltips" type="boolean" default="true">
  Whether to show tooltips on hover. Overrides the `appearance.showTooltips` setting in `GraphConfig`.
</ParamField>

<ParamField path="showHoverEffects" type="boolean" default="true">
  Whether to show hover effects (line markers, bar highlighting, etc.).
</ParamField>

<ParamField path="animateTransitions" type="boolean" default="true">
  Whether to animate the graph on initial render and when data changes. Overrides the `appearance.animateTransitions`
  setting in `GraphConfig`.
</ParamField>

<ParamField path="isExplorable" type="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
</ParamField>

```tsx theme={null}
// 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

```tsx theme={null}
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

```tsx theme={null}
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

<Accordion title="GraphSizing">
  ```tsx theme={null}
  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 };
  ```
</Accordion>

<Accordion title="GraphTitleRenderProps">
  ```tsx theme={null}
  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;
  }
  ```
</Accordion>

## 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" />`   |

## Related

* [GraphProvider](/sdk/reference/graph-provider) - State management and configuration
* [Error Handling](/sdk/advanced/error-handling) - Error handling patterns