Node Grouping & Subflow

createNodeGroupPlugin lets you group multiple selected nodes into a parent-child container with a single call, supporting collapse/expand and ungroup operations. Perfect for AI Agent orchestration, BPMN subgraphs, and complex multi-stage pipelines.

Quick Start

import { createNodeGroupPlugin } from '@yh-ui/flow'

onMounted(() => {
  // Install the plugin; it mounts groupSelectedNodes / ungroupNodes etc. onto flowRef.value
  flowRef.value?.usePlugin(
    createNodeGroupPlugin({
      groupIdPrefix: 'grp', // ID prefix for auto-generated group IDs
      paddingX: 40, // Horizontal padding around child nodes (px)
      paddingY: 50 // Vertical padding around child nodes (px)
    })
  )
})

// After install, call group methods on flowRef.value:
flowRef.value?.groupSelectedNodes('My Group') // → group and return groupId
flowRef.value?.ungroupNodes(groupId) // → ungroup
flowRef.value?.toggleGroupCollapse(groupId) // → toggle collapse/expand

Group / Ungroup Nodes

Select 2+ nodes:

Node A

Node B

Node C

Node D

Output

💡 Click to select, Shift for multi-select, then click "Group"

Select nodes then group or ungroup with one click

API

Install Plugin

import { createNodeGroupPlugin } from '@yh-ui/flow'

onMounted(() => {
  flowRef.value?.usePlugin(createNodeGroupPlugin(options))
})

FlowInstance Extended Methods

Automatically mounted onto flowRef.value after usePlugin is called

Method	Signature	Description
groupSelectedNodes	(label?: string) => string | null	Groups all selected nodes; returns group ID or null if < 2 selected
ungroupNodes	(groupId: string) => void	Ungroup: restore children to absolute coordinates as top-level nodes
toggleGroupCollapse	(groupId: string) => void	Toggle group collapse/expand (also hides/shows connected edges)
isGroupCollapsed	(groupId: string) => boolean	Check if a group is currently collapsed
getGroupChildren	(groupId: string) => Node[]	Get all child nodes of a group
getGroupRegistry	() => Map<string, GroupInfo>	Get full group registry (for debugging)

NodeGroupOptions

Prop	Type	Default	Description
enabled	boolean	true	Enable plugin
groupNodeType	string	'group'	Render type for group node
paddingX	number	40	Horizontal padding inside the group container (px)
paddingY	number	50	Vertical padding inside the group container (px)
groupIdPrefix	string	'group'	Prefix for auto-generated group IDs (e.g. 'grp' → 'grp-1')