JavaScript is required
relation-graph Relational Data Visualization and Editing
Sign in 中文 GitHub

Getting Started

Purpose and Scope

This page provides installation and basic usage instructions for relation-graph across all supported platforms (Vue 2, Vue 3, React, Svelte, and Web Components). It covers package installation, basic component integration, and core usage patterns. For detailed information about the internal architecture, see Core Architecture. For configuration options, see Configuration & Options. For API methods, see API Reference.

Installation

relation-graph is distributed as separate npm packages for each supported framework. All packages share the same core logic but provide framework-specific wrappers.

Framework Package Name Version Installation Command
Vue 2 @relation-graph/vue2 3.0.3 npm install @relation-graph/vue2
Vue 3 @relation-graph/vue 3.0.3 npm install @relation-graph/vue
React @relation-graph/react 3.0.3 npm install @relation-graph/react
Svelte @relation-graph/svelte 3.0.3 npm install @relation-graph/svelte
Web Components @relation-graph/web-components 3.0.3 npm install @relation-graph/web-components

Sources: platforms/vue2/package.json:1-65, platforms/vue3/package.json:1-65, platforms/react/package.json:1-65, platforms/svelte/package.json:1-65, platforms/web-components/package.json:1-65

Package Architecture Overview

The following diagram illustrates how the platform-specific packages relate to the shared core:

graph TB
    subgraph "Platform Packages (npm)"
        Vue2["@relation-graph/vue2
Vue 2.x compatible"]
        Vue3["@relation-graph/vue
Vue 3.x compatible"]
        React["@relation-graph/react
React compatible"]
        Svelte["@relation-graph/svelte
Svelte compatible"]
        WebComp["@relation-graph/web-components
Framework-agnostic"]
    end
    
    subgraph "Shared Core (Internal)"
        RGCore["RelationGraphCore
Framework-agnostic business logic"]
        DataProvider["RGDataProvider
Reactive data abstraction"]
        Types["Type Definitions
RGNode, RGLine, RGOptions"]
    end
    
    Vue2 --> RGCore
    Vue3 --> RGCore
    React --> RGCore
    Svelte --> RGCore
    WebComp --> RGCore
    
    RGCore --> DataProvider
    RGCore --> Types
    DataProvider --> Types

Sources: package.json:1-65, platforms/vue2/package.json:1-65, platforms/vue3/package.json:1-65, platforms/react/package.json:1-65

Basic Usage by Platform

Vue 2

Vue 2 usage involves importing the RelationGraph component and using it in templates with v-bind for options and event listeners with @ syntax.

Component Structure:

Key Integration Points:

Template:
  <RelationGraph :options="graphOptions" @onNodeClick="handleNodeClick">
    <!-- Custom node rendering via #node slot -->
    <template #node="{ node }">
      <!-- Custom node content -->
    </template>
  </RelationGraph>

Script:
  - Import RelationGraph component
  - Define options object (RGOptions type)
  - Use ref.getInstance() to access RelationGraphCore instance
  - Register event handlers with @ syntax

Instance Access Pattern: The component exposes an getInstance() method via template ref. This method returns the underlying RelationGraphCore instance but displays a warning message from packages/platforms/vue2/src/core4vue/RelationGraph.vue:170-172 because Vue 2 uses reactive data integration that should be accessed through the data provider pattern. See Reactive Data Integration for details.

Sources: packages/platforms/vue2/src/core4vue/RelationGraph.vue:1-184, packages/platforms/vue2/src/core4vue/RelationGraphUI.vue:1-136

Vue 3

Vue 3 usage leverages Composition API and setup script syntax with improved TypeScript support.

Component Structure:

Key Integration Points:

Template:
  <RelationGraph :options="graphOptions" @onNodeClick="handleNodeClick">
    <!-- Custom rendering slots: #node, #line, #canvas, #canvas-above, #background -->
  </RelationGraph>

Script Setup:
  - Import RelationGraph from '@relation-graph/vue'
  - Define options as ref or reactive object
  - Use template ref with .getInstance() to access core instance
  - Event handlers registered with @eventName syntax

Slot Naming Changes: The Vue 3 version enforces slot naming conventions. Deprecated slot names throw errors at packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:41-52. Current slot names:

  • #view (formerly #graph-plug)
  • #canvas (formerly #canvas-plug)
  • #canvas-above (formerly #canvas-plug-above)
  • #node-expand-button (formerly #node-expand-holder)

Sources: packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:1-76, packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraphUI.vue:1-97

React

React integration uses hooks pattern with useGraphInstance and functional components.

Component Structure:

Key Integration Points:

JSX:
  <RelationGraph ref={graphRef} options={graphOptions}>
    {/* Custom node slot via RGSlotOnNode */}
    <RGSlotOnNode>
      {(node: RGNodeSlotProps) => (
        <div>{node.text}</div>
      )}
    </RGSlotOnNode>
    
    {/* Other slots: RGSlotOnLine, RGSlotOnView, RGSlotOnCanvas, RGSlotOnCanvasAbove */}
  </RelationGraph>

Script:
  - Import RelationGraph from '@relation-graph/react'
  - Create ref with useRef<RelationGraphExpose>(null)
  - Access instance via ref.current?.getInstance()
  - Pass options as props object

Slot Pattern: React uses a custom slot pattern with typed components like RGSlotOnNode and RGSlotOnLine. Each slot component expects a function as children that receives typed props. The slot detection logic is at packages/platforms/react/src/relation-graph/src/core4react/RelationGraphView.tsx:49-80.

Sources: packages/platforms/react/src/relation-graph/RelationGraph.tsx:1-41, packages/platforms/react/src/relation-graph/src/core4react/RelationGraphView.tsx:1-150

Svelte

Svelte integration uses stores for reactive state management.

Component Structure:

Key Integration Points:

Svelte Template:
  <RelationGraph {options} on:onNodeClick={handleNodeClick}>
    <!-- Custom slots with let: directives -->
    <svelte:fragment slot="node" let:node let:nodeConfig>
      <!-- Custom node rendering -->
    </svelte:fragment>
  </RelationGraph>

Script:
  - Import RelationGraph from '@relation-graph/svelte'
  - Define options object
  - Access instance via useGraphInstance() composable
  - Event handlers with on:eventName syntax

Reactive Store Pattern: The Svelte version uses $optionsStore syntax for reactive subscriptions at packages/platforms/svelte/src/core4svelte/RelationLinkerUI.svelte:14-15. This integrates with Svelte’s built-in store system.

Sources: packages/platforms/svelte/src/core4svelte/RelationLinkerUI.svelte:1-67

Web Components

Web Components provide framework-agnostic usage through custom elements.

Component Structure:

Key Integration Points:

HTML:
  <relation-graph id="graph1">
    <!-- Configuration passed via properties or attributes -->
  </relation-graph>

JavaScript:
  - Import and register custom elements
  - Access via DOM: document.getElementById('graph1')
  - Set options via JavaScript properties
  - Listen to events via addEventListener

Sources: platforms/web-components/package.json:1-65

Component Integration Flow

The following diagram shows how user application code integrates with the RelationGraph component wrapper and the underlying core instance:

graph TD
    UserApp["User Application Code
Vue/React/Svelte/etc."]
    
    subgraph "Component Wrapper Layer"
        RGComp["RelationGraph Component
Framework-specific wrapper"]
        RGUI["RelationGraphUI Component
Canvas and UI orchestration"]
    end
    
    subgraph "Instance Management"
        Provider["RGProvider / RGDataProvider
Context/injection system"]
        GraphStore["graphStore
Provides graphInstance + options"]
    end
    
    subgraph "Core Layer"
        RGCore["RelationGraphCore Instance
Business logic and state"]
    end
    
    UserApp -->|"Provides: options, initialData
Registers: event handlers"| RGComp
    UserApp -->|"Gets instance via:
ref.getInstance() / useGraphInstance()"| RGComp
    
    RGComp -->|"Creates/injects"| Provider
    RGComp -->|"Renders"| RGUI
    
    Provider -->|"Manages"| GraphStore
    Provider -->|"Creates (if new)"| RGCore
    
    GraphStore -->|"Stores reference"| RGCore
    
    RGUI -->|"Reads from"| GraphStore
    RGUI -->|"Calls methods on"| RGCore
    
    RGComp -->|"setOptions()
setEventEmitHook()"| RGCore

Sources: packages/platforms/vue2/src/core4vue/RelationGraph.vue:1-184, packages/platforms/react/src/relation-graph/RelationGraph.tsx:1-41, packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:1-76

Core Concepts

RelationGraphCore Instance

The RelationGraphCore class (detailed in Core Architecture) is the central object that manages graph state, layout, rendering, and user interactions. Each component creates or receives a single instance.

Instance Creation:

Instance Access: All platforms expose an getInstance() method on the component ref/reference, but it includes a warning about data provider usage. The preferred pattern is to use the reactive data integration system (see Reactive Data Integration).

Options Configuration

Options are provided via the options prop and conform to the RGOptions type. The options object configures:

  • Layout algorithm (see Layout System)
  • Visual styling (colors, line width, node borders)
  • Interaction behaviors (zoom, drag, edit mode)
  • Performance settings (viewport culling, canvas rendering)

For complete option reference, see Configuration & Options.

Initial Data Structure

Initial data can be provided via the initialData prop (Vue 2/Vue 3) or through imperative methods after mounting. The data structure includes:

RGJsonData:
  - nodes: JsonNode[]
      - id: string (required)
      - text: string
      - x, y: number (optional, calculated by layout if omitted)
      - Additional custom properties
  
  - lines: JsonLine[]
      - from: string (node id)
      - to: string (node id)
      - text: string (optional)
      - Additional custom properties

Data transformation from JsonNode/JsonLine to internal RGNode/RGLine types is handled by the core (see Data Transformation Pipeline).

Getting the Instance - Important Warning

All platform implementations provide getInstance() method but include warning messages:

These warnings indicate that direct instance access bypasses the reactive data provider system. The definitelyNoDataProviderNeeded option flag suppresses these warnings if you explicitly want direct access.

Sources: packages/platforms/vue2/src/core4vue/RelationGraph.vue:170-176, packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:57-64, packages/platforms/react/src/relation-graph/RelationGraph.tsx:16-25

Data Provider Pattern

The following diagram illustrates how the data provider pattern works across different frameworks:

graph LR
    subgraph "User Code"
        UserComponent["Application Component"]
    end
    
    subgraph "RelationGraph Component"
        RGWrapper["RelationGraph Wrapper
(Vue2/Vue3/React/Svelte)"]
    end
    
    subgraph "Data Provider Layer"
        ProviderVue2["Vue2Provider
Vue.set() for reactivity"]
        ProviderVue3["Vue3Provider
ref()/reactive()"]
        ProviderReact["ReactProvider
useState hooks"]
        ProviderSvelte["SvelteProvider
writable stores"]
    end
    
    subgraph "Core Instance"
        RGCore["RelationGraphCore"]
        GraphData["RGGraphData
nodes: RGNode[]
lines: RGLine[]"]
    end
    
    UserComponent -->|"Pass options,
register events"| RGWrapper
    
    RGWrapper -->|"setReactiveData4Vue2()
setReactiveData4Vue3()
setReactiveData4React()
setReactiveData4Svelte()"| ProviderVue2
    RGWrapper --> ProviderVue3
    RGWrapper --> ProviderReact
    RGWrapper --> ProviderSvelte
    
    ProviderVue2 -->|"Makes reactive"| GraphData
    ProviderVue3 -->|"Makes reactive"| GraphData
    ProviderReact -->|"Makes reactive"| GraphData
    ProviderSvelte -->|"Makes reactive"| GraphData
    
    RGCore -->|"Contains"| GraphData
    RGCore -->|"Updates via
addNode(), updateNode(),
_dataUpdated()"| GraphData
    
    GraphData -.->|"Reactive updates
trigger re-render"| RGWrapper

How It Works:

  1. User component passes options and initialData to RelationGraph component
  2. RelationGraph creates or receives RelationGraphCore instance
  3. Platform-specific data provider wraps the core’s graphData object
  4. When core updates data via addNode(), updateNode(), etc., the data provider detects changes
  5. Framework-specific reactivity system triggers component re-render
  6. UI components read latest data from reactive stores/refs/state

For detailed implementation, see Data Management System and Reactive Data Integration.

Sources: packages/platforms/vue2/src/core4vue/RelationGraph.vue:158-164, packages/platforms/react/src/relation-graph/RelationGraph.tsx:34-36

RelationLinker Component

In addition to the full RelationGraph component, each platform provides a RelationLinker component that renders only lines (no nodes). This is useful for connecting elements in the DOM that are positioned by other means.

Component Files:

Usage Pattern:

RelationLinker accepts:
  - options: RGOptions
  - lines: JsonLine[] (required prop)
  
Renders:
  - SVG paths connecting specified coordinate points
  - No layout algorithm applied
  - No node rendering

Sources: packages/platforms/vue2/src/core4vue/RelationLinker.vue:1-128, packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationLinker.vue:1-35, packages/platforms/react/src/relation-graph/src/core4react/RelationLinkerView.tsx:1-110

Next Steps

After completing basic integration:

For understanding the internal architecture that powers these components, see Core Architecture.