Class Shape

A handle to a single shape on a Visio page.

Obtain instances via Page.addShape, Page.getShapes, Page.getShapeById, or Page.findShapes.

Example

const shape = await page.addShape({ text: 'Box', x: 1, y: 1, width: 2, height: 1 });
await shape.setStyle({ fillColor: '#4472C4', fontColor: '#ffffff', bold: true });
console.log(shape.id, shape.x, shape.y);

Constructors

constructor

new Shape(
    internalShape: VisioShape,
    pageId: string,
    pkg: VisioPackage,
    modifier?: ShapeModifier,
): Shape
Parameters
- internalShape: VisioShape
- pageId: string
- pkg: VisioPackage
- Optionalmodifier: ShapeModifier
Returns Shape
- Defined in Shape.ts:45

Accessors

angle

get angle(): number
Current rotation angle in degrees (0 if no Angle cell is set).

Returns number
- Defined in Shape.ts:245

height

get height(): number
Returns number
- Defined in Shape.ts:91

id

get id(): string
Returns string
- Defined in Shape.ts:54

isGroup

get isGroup(): boolean
true if this shape is a Group (i.e. it can contain nested child shapes). Use shape.getChildren() to retrieve those children.

Returns boolean
- Defined in Shape.ts:74

name

get name(): string
Returns string
- Defined in Shape.ts:58

text

get text(): string
Returns string
- Defined in Shape.ts:78

type

get type(): string
The shape's Type attribute — 'Group' for group shapes, 'Shape' (or undefined normalised to 'Shape') for regular shapes.

Returns string
- Defined in Shape.ts:66

width

get width(): number
Returns number
- Defined in Shape.ts:87

x

get x(): number
Returns number
- Defined in Shape.ts:95

y

get y(): number
Returns number
- Defined in Shape.ts:99

Methods

addConnectionPoint

addConnectionPoint(point: ConnectionPointDef): number
Add a connection point to this shape. Returns the zero-based index (IX) of the newly added point.
Parameters
- point: ConnectionPointDef
Returns number
- Defined in Shape.ts:123

addData

addData(key: string, data: ShapeData): this
Parameters
- key: string
- data: ShapeData
Returns this
- Defined in Shape.ts:184

addHyperlink

addHyperlink(address: string, description?: string): Promise<Shape>
Parameters
- address: string
- Optionaldescription: string
Returns Promise<Shape>
- Defined in Shape.ts:318

addListItem

addListItem(item: Shape): Promise<Shape>
Parameters
- item: Shape
Returns Promise<Shape>
- Defined in Shape.ts:298

addMember

addMember(memberShape: Shape): Promise<Shape>
Parameters
- memberShape: Shape
Returns Promise<Shape>
- Defined in Shape.ts:293

addPropertyDefinition

addPropertyDefinition(
    name: string,
    type: number,
    options?: { invisible?: boolean; label?: string },
): this
Parameters
- name: string
- type: number
- options: { invisible?: boolean; label?: string } = {}
Returns this
- Defined in Shape.ts:174

addToLayer

addToLayer(layer: number | Layer): Promise<Shape>
Alias for assignLayer. Adds this shape to a layer.
Parameters
- layer: number | Layer
Returns Promise<Shape>
- Defined in Shape.ts:361

applyStyle

applyStyle(styleId: number, which?: "text" | "fill" | "all" | "line"): this
Apply a document-level stylesheet to this shape. Create styles via doc.createStyle() and pass the returned id.
Parameters
- styleId: number
  The stylesheet ID to apply.
- which: "text" | "fill" | "all" | "line" = 'all'
  'all' (default) applies to line, fill, and text; 'line', 'fill', or 'text' applies to only that category.
Returns this
- Defined in Shape.ts:135

assignLayer

assignLayer(layer: number | Layer): Promise<Shape>
Parameters
- layer: number | Layer
Returns Promise<Shape>
- Defined in Shape.ts:352

connectTo

connectTo(
    targetShape: Shape,
    beginArrow?: string,
    endArrow?: string,
    style?: ConnectorStyle,
    fromPort?: ConnectionTarget,
    toPort?: ConnectionTarget,
): Promise<Shape>
Parameters
- targetShape: Shape
- OptionalbeginArrow: string
- OptionalendArrow: string
- Optionalstyle: ConnectorStyle
- OptionalfromPort: ConnectionTarget
- OptionaltoPort: ConnectionTarget
Returns Promise<Shape>
- Defined in Shape.ts:107

delete

delete(): Promise<void>
Returns Promise<void>
- Defined in Shape.ts:103

flipX

flipX(enabled?: boolean): Promise<Shape>
Flip the shape horizontally. Pass false to un-flip.
Parameters
- enabled: boolean = true
Returns Promise<Shape>
- Defined in Shape.ts:278

flipY

flipY(enabled?: boolean): Promise<Shape>
Flip the shape vertically. Pass false to un-flip.
Parameters
- enabled: boolean = true
Returns Promise<Shape>
- Defined in Shape.ts:287

getChildren

getChildren(): Shape[]

Return the direct child shapes of this group. Returns an empty array for non-group shapes or groups with no children.

Only direct children are returned — grandchildren are accessible by calling getChildren() on the child shape.

Returns Shape[]

Example

const group = await page.addShape({ text: 'G', x: 5, y: 5, width: 4, height: 4, type: 'Group' });
await page.addShape({ text: 'Child A', x: 1, y: 1, width: 1, height: 1 }, group.id);
await page.addShape({ text: 'Child B', x: 2, y: 1, width: 1, height: 1 }, group.id);
group.getChildren(); // → [Shape('Child A'), Shape('Child B')]

getHyperlinks

getHyperlinks(): ShapeHyperlink[]
Read back all hyperlinks attached to this shape.

Returns ShapeHyperlink[]
- Defined in Shape.ts:214

getLayerIndices

getLayerIndices(): number[]
Read back the layer indices this shape is assigned to. Returns an empty array if the shape has no layer assignment.

Returns number[]
- Defined in Shape.ts:222

getProperties

getProperties(): Record<string, ShapeData>
Read back all custom property (shape data) entries written to this shape. Returns a map of property key → ShapeData. Values are coerced to the declared Visio type (Number, Boolean, Date, or String).

Returns Record<string, ShapeData>
- Defined in Shape.ts:207

linkToPage

linkToPage(targetPage: { name: string }, description?: string): Promise<Shape>
Parameters
- targetPage: { name: string }
- Optionaldescription: string
Returns Promise<Shape>
- Defined in Shape.ts:323

placeBelow

placeBelow(targetShape: Shape, options?: { gap: number }): Promise<Shape>
Parameters
- targetShape: Shape
- options: { gap: number } = ...
Returns Promise<Shape>
- Defined in Shape.ts:160

placeRightOf

placeRightOf(targetShape: Shape, options?: { gap: number }): Promise<Shape>
Parameters
- targetShape: Shape
- options: { gap: number } = ...
Returns Promise<Shape>
- Defined in Shape.ts:145

resize

resize(width: number, height: number): Promise<Shape>
Resize the shape to the given width and height (in inches). Updates LocPinX/LocPinY to keep the centre-pin at width/2, height/2.
Parameters
- width: number
- height: number
Returns Promise<Shape>
- Defined in Shape.ts:265

resizeToFit

resizeToFit(padding?: number): Promise<Shape>
Parameters
- padding: number = 0.25
Returns Promise<Shape>
- Defined in Shape.ts:304

rotate

rotate(degrees: number): Promise<Shape>
Rotate the shape to an absolute angle (degrees, clockwise). Replaces any existing rotation.
Parameters
- degrees: number
Returns Promise<Shape>
- Defined in Shape.ts:254

setPropertyValue

setPropertyValue(name: string, value: string | number | boolean | Date): this
Parameters
- name: string
- value: string | number | boolean | Date
Returns this
- Defined in Shape.ts:179

setStyle

setStyle(style: ShapeStyle): Promise<Shape>
Parameters
- style: ShapeStyle
Returns Promise<Shape>
- Defined in Shape.ts:140

setText

setText(newText: string): Promise<void>
Parameters
- newText: string
Returns Promise<void>
- Defined in Shape.ts:82

toPage

toPage(targetPage: { name: string }, description?: string): Promise<Shape>
Adds an internal link to another page. Shows up in the right-click menu in Visio.
Parameters
- targetPage: { name: string }
  The Page object to link to
- Optionaldescription: string
  Text to show in the menu
Returns Promise<Shape>
- Defined in Shape.ts:348

toUrl

toUrl(url: string, description?: string): Promise<Shape>
Adds an external hyperlink to the shape. Shows up in the right-click menu in Visio.
Parameters
- url: string
  External URL (e.g. https://google.com)
- Optionaldescription: string
  Text to show in the menu
Returns Promise<Shape>
- Defined in Shape.ts:338

Class Shape

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Shape

Accessors

angle

Returns number

height

Returns number

id

Returns string

isGroup

Returns boolean

name

Returns string

text

Returns string

type

Returns string

width

Returns number

x

Returns number

y

Returns number

Methods

addConnectionPoint

Parameters

Returns number

addData

Parameters

Returns this

addHyperlink

Parameters

Returns Promise<Shape>

addListItem

Parameters

Returns Promise<Shape>

addMember

Parameters

Returns Promise<Shape>

addPropertyDefinition

Parameters

Returns this

addToLayer

Parameters

Returns Promise<Shape>

applyStyle

Parameters

Returns this

assignLayer

Parameters

Returns Promise<Shape>

connectTo

Parameters

Returns Promise<Shape>

delete

Returns Promise<void>

flipX

Parameters

Returns Promise<Shape>

flipY

Parameters

Returns Promise<Shape>

getChildren

Returns Shape[]

Example

getHyperlinks

Returns ShapeHyperlink[]

getLayerIndices

Returns number[]

getProperties

Returns Record<string, ShapeData>

linkToPage