Custom Node Templates

yh-flow provides a powerful custom node template system that allows you to register reusable node templates and quickly create standardized nodes through configuration data.

Core Concepts

Template Registration

Use the registerCustomNodeTemplate function to register custom node templates:

import { registerCustomNodeTemplate, type CustomNodeTemplate } from '@yh-ui/flow'
import MyCustomNode from './MyCustomNode.vue'

const template: CustomNodeTemplate = {
  type: 'my-custom',
  component: MyCustomNode,
  defaultData: {
    label: 'Default Title',
    icon: 'star',
    status: 'active'
  },
  defaultWidth: 200,
  defaultHeight: 80,
  description: 'This is a custom business node template'
}

// Register the template
registerCustomNodeTemplate(template)

Creating Nodes from Templates

After registering a template, you can quickly create nodes using the createNodeFromTemplate method:

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

// Create node from template
const newNode = createNodeFromTemplate(
  'my-custom', // Template type
  'node-1', // Node ID
  { x: 100, y: 200 }, // Position
  {
    // Optional override config
    data: { label: 'Custom Title' }
  }
)

Usage Examples

Template canvas

Template Workspace

API Reference

Registration Functions

Function	Description	Parameters
registerCustomNodeTemplate(template)	Register custom node template	template: CustomNodeTemplate
getCustomNodeTemplate(type)	Get template by type	type: string
getAllCustomNodeTemplates()	Get all registered templates	-
hasCustomNodeTemplate(type)	Check if template exists	type: string
createNodeFromTemplate(type, id, position, overrides)	Create node from template	See below

createNodeFromTemplate Parameters

Parameter	Type	Required	Description
type	string	Yes	Template type
id	string	Yes	New node ID
position	{ x: number, y: number }	Yes	Node position
overrides	Partial<Node>	No	Override default config

CustomNodeTemplate Interface

interface CustomNodeTemplate {
  type: string // Unique template identifier
  component: Component // Vue component
  defaultData?: Record<string, unknown> // Default data
  defaultWidth?: number // Default width
  defaultHeight?: number // Default height
  handles?: NodeHandleBounds // Handle configuration
  description?: string // Template description
}

Best Practices

1. Centralize template management: Store all custom templates in a dedicated file
2. Provide default data: Use defaultData to provide sensible defaults for business nodes
3. Type safety: Define TypeScript interfaces for custom node data to ensure type safety
4. Component reuse: The same component can be registered as different template types, differentiated by defaultData

TIP

Combining with the Flow instance's createNodeFromTemplate method enables automatic template-based node creation when dragging and dropping nodes.