Overview
The WeaveRectangleNode class represents a basic rectangular shape within the Weave.js canvas. It is one of the fundamental visual building blocks for creating collaborative tools, diagrams, design layouts, and interactive content.
Built on top of Konva’s Rect class shape under the hood, the WeaveRectangleNode offers a simple yet powerful primitive that supports full interaction, styling, and real-time synchronization.
Rectangles are ideal for:
-
Building interactive visual elements (e.g., cards, sections, containers).
-
Forming basic layout structures for more complex visual tools.
-
Acting as a foundational primitive in diagrams, whiteboards, or flow-based applications.
Rectangle nodes support an optional text label that is displayed centred inside the shape.
The label can be edited interactively by double-clicking the rectangle while it is selected.
All label appearance properties (font, colour, alignment, padding, …) are configurable via the
label* props described below.
The class extends the WeaveNode class
Label engine
By default the label is rendered with Konva’s text and edited through a DOM textarea overlay (legacy).
Set config.label.engine to native to render the label with the on-canvas text engine and edit it
with the native editing session instead: no DOM overlay, and caret and selection are drawn on the canvas.
new WeaveRectangleNode({ config: { label: { engine: "native" } } });Both engines read and write the same labelText and label* props, so clients using different engines
can edit the same document. The native engine enables rich text in labels (bold, italic, underline, lists, alignment). Formatted content is stored in the optional labelBlocks prop, and labelText always holds the plain text, so the legacy engine shows the plain text.
Label edit events
With the native label engine the node emits onEnterShapeLabelEditMode when a label edit session starts and
onExitShapeLabelEditMode when it ends. Exit receives { node: Konva.Group }; enter also receives the live
session, so an app can build a formatting toolbar by running format commands on it. While editing,
onShapeLabelFormatChange receives { node, format } whenever the selection format changes.
The legacy engine does not emit them.
TypeScript types
type WeaveNodeTransformerProperties = Konva.TransformerConfig;
type WeaveShapeLabelConfig = {
engine: "legacy" | "native"; // default "legacy"
};
type WeaveRectangleProperties = {
transform: WeaveNodeTransformerProperties;
label?: Partial<WeaveShapeLabelConfig>;
};
type WeaveRectangleNodeParams = {
config: Partial<WeaveRectangleProperties>;
};
type WeaveShapeLabelProps = {
labelText?: string;
labelFontFamily?: string;
labelFontSize?: number;
labelFontStyle?: string;
labelFontVariant?: string;
labelTextDecoration?: string;
labelFill?: string;
labelAlign?: string;
labelVerticalAlign?: string;
labelLetterSpacing?: number;
labelLineHeight?: number;
labelPaddingX?: number;
labelPaddingY?: number;
labelBlocks?: WeaveTextBlock[]; // rich content written by the native engine
};Parameters
For WeaveRectangleNodeParams:
| Property | Type | Required | Description |
|---|---|---|---|
|
|
Required |
Config parameters for the node. |
For WeaveRectangleProperties:
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
|
|
|
Setup the transform properties for the rectangle (if can be resized, rotated, anchors, etc.). |
Label properties
The following props control the optional text label rendered inside the rectangle.
They map directly to WeaveShapeLabelProps and are all optional — omit them to use the defaults.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
|
|
Text content of the label. Set to an empty string to hide the label. |
||
|
|
|
CSS font-family string for the label text. |
|
|
|
|
Font size of the label text in pixels. |
|
|
|
|
Font style for the label. Accepts CSS font-style/weight keywords or a numeric weight (e.g. "normal", "bold", "italic", "bold italic", "700"). |
|
|
|
|
CSS font-variant for the label (e.g. "normal", "small-caps"). |
|
|
|
CSS text-decoration for the label (e.g. "underline", "line-through"). |
||
|
|
|
Colour of the label text in hex format (e.g. #RRGGBBAA). |
|
|
|
|
Horizontal alignment of the label text ("left", "center", "right"). |
|
|
|
|
Vertical alignment of the label text ("top", "middle", "bottom"). |
|
|
|
|
Letter spacing for the label text in pixels. |
|
|
|
|
Line-height multiplier for the label text. |
|
|
|
|
Horizontal inset (padding) in pixels applied on each side of the label area. |
|
|
|
|
Vertical inset (padding) in pixels applied on the top and bottom of the label area. |
Default values
const WEAVE_TRANSFORMER_ANCHORS = {
["TOP_LEFT"]: "top-left",
["TOP_CENTER"]: "top-center",
["TOP_RIGHT"]: "top-right",
["MIDDLE_RIGHT"]: "middle-right",
["MIDDLE_LEFT"]: "middle-left",
["BOTTOM_LEFT"]: "bottom-left",
["BOTTOM_CENTER"]: "bottom-center",
["BOTTOM_RIGHT"]: "bottom-right",
};
const WEAVE_DEFAULT_ENABLED_ANCHORS: string[] = Object.values(
WEAVE_TRANSFORMER_ANCHORS
);
const WEAVE_DEFAULT_TRANSFORM_PROPERTIES: WeaveNodeTransformerProperties = {
rotateEnabled: true,
resizeEnabled: true,
enabledAnchors: WEAVE_DEFAULT_ENABLED_ANCHORS,
borderStrokeWidth: 3,
padding: 0,
};
const WEAVE_SHAPE_LABEL_DEFAULTS: WeaveShapeLabelProps = {
labelText: "",
labelFontFamily: "Arial, sans-serif",
labelFontSize: 14,
labelFontStyle: "normal",
labelFontVariant: "normal",
labelTextDecoration: "",
labelFill: "#000000",
labelAlign: "center",
labelVerticalAlign: "middle",
labelLetterSpacing: 0,
labelLineHeight: 1,
labelPaddingX: 8,
labelPaddingY: 8,
};