Nodes

Introduction

Nodes are the core visual elements in Weave.js, they represent everything you see and interact with on the canvas. From simple shapes like rectangles and lines, to text, images, and complex containers like frames, Nodes are the building blocks of your collaborative interface.

Each Node is based on Konva.js primitives and enhanced with interactive behavior, styling, and real-time sync capabilities. Nodes can be selected, moved, edited, grouped, and extended, making them flexible enough to power everything from diagram tools to whiteboards and custom UIs.

In short, if it shows up on the canvas in Weave.js, it's probably a Node.

Available nodes

Weave.js team maintain a set of base nodes, think of them as the minimal nodes to build visual collaborative applications. This are the nodes:

Structure

Stage

The Stage node is the root canvas container in Weave.js. It serves as the entry point for rendering all other visual or layout Nodes and manages the overall coordinate system.

Layer

The Layer node is a logical container within the Stage. It allows you to separate visual elements, for example: background grids, interactive elements, or UI overlays, into distinct rendering layers.

Grouping

Group

The Group node is a container for organizing multiple nodes into a single, movable and transformable unit. It allows you to nest shapes or other groups together, enabling you to apply transformations like positioning, scaling, rotation,or selection as one unified object.

Frame

The Frame node is a container-like visual element used to group and organize other nodes within a pre-defined boundary. It functions as a structured layout region, often used to represent panels, sections, or modular components on the canvas.

Drawing

Rectangle

The Rectangle node is a simple, versatile primitive shape used to render rectangular elements on the canvas. It supports customizable properties such as position, size, fill color, stroke, corner radius and more.

Ellipse

The Ellipse node is a simple, versatile primitive shape used to render ellipses (or circles) elements on the canvas. It supports customizable properties such as position, axis radius, fill color, stroke and more.

Regular Polygon

The Regular Polygon node is a simple, versatile primitive shape used to render regular polygons elements on the canvas. It supports customizable properties such as position, radius, sides, fill color, stroke and more.

Line

The Line node represents a customizable straight or curved line on the canvas. It supports features like multiple points, stroke color, width, dash patterns, and smoothing options.

Text

The Text node is used to display editable or static text on the canvas. It supports rich styling options including font size, family, color, alignment, and line height.

Image

The Image Node allows you to render images directly onto the canvas. It supports properties like position, scale, opacity, and filters.

Star

The Star node is a simple, versatile primitive shape used to render star elements on the canvas. It supports customizable properties such as position, inner and outer radius, fill color, stroke and more.

Arrow

The Arrow node is a simple, versatile primitive shape used to render arrow elements on the canvas. It supports customizable properties such as position, several segments, fill color, stroke and more.

Custom Nodes

Developers can also build their own custom nodes, empowering this way their applications with new visual nodes with behavior closer to the needs of their applications.

For this we provide an extension mechanism that allows to define your own nodes and use them on your application.

WeaveNode class

In Weave.js a Node is a class that extends the WeaveNode abstract class, and implements a set of methods that define the Node behavior.

Access the Weave instance

You can access Weave.js main instance via this.instance.

To create a custom node, create a class that extends the WeaveNode abstract class, and implement the following attributes and methods:

nodeType

All nodes must define a property:

nodeType: string;

Which defines the node identity. The nodeType attribute must be unique among other nodes.

create

create(key: string, props: WeaveElementAttributes): WeaveStateElement

The create method receives:

key: is the identifier of the node on the rendering tree - and is unique.
props: the properties of the node.

It should return a JSON representation of the node.

Check the base implementation

Most times this method is not needed to extend as the implementation on the base class, covers most use cases.

onRender

onRender(props: WeaveElementAttributes): WeaveElementInstance

The onRender method is the one responsible for rendering the node on the canvas, It's a good place to initialize the nodes, events, etc.

onUpdate

onUpdate(
  instance: WeaveElementInstance,
  nextProps: WeaveElementAttributes
): void

The onUpdate method is called anytime that the nodes needs to update on the canvas, it receives the actual canvas instance (Konva element) of the node and the new props.

onDestroy

onDestroy(nodeInstance: WeaveElementInstance): void

The onDestroy method is called when the canvas instance needs to be disposed.

serialize

serialize(instance: WeaveElementInstance): WeaveStateElement

The serialize method transform a canvas instance (Konva element) into its JSON representation so it can be sent over the wire for sync with other peers or to persist the model server-side.

Konva.Node Augmentation

Our WeaveNode base class extend the Konva.Node class to define several functions:

getTransformerProperties

getTransformerProperties(): WeaveNodeTransformerProperties

This function allows you to override how when node is selected it can: rotate, resize and if is resizable which anchors for resizing will be available.

By default, all nodes can rotate, resize and the default anchors are:

const DEFAULT_ANCHORS_ENABLED: string[] = [
  "top-left",
  "top-center",
  "top-right",
  "middle-right",
  "middle-left",
  "bottom-left",
  "bottom-center",
  "bottom-right",
];

movedToContainer

movedToContainer(): void

Function that is called when the node changes from one container to another.

updatePosition

updatePosition(): void

Function that is called when a node updates its position, its useful when trying to move Nodes my its children and not its parents, check how the Frame node is coded and look for how it uses the updatePosition callback.