Connector

Connector.Connector

Connector

The connector item creates lines to connect two items on the board.
Connectors are useful when drawing diagrams, flow charts, and mind maps.

The line of a connector item must have two terminal points: a start and an end point.
These points are located on the area of the board items that they connect.
If you remove either the start point, the end point, or both, the connector line is removed as well.

It's possible to style connector lines by defining properties such as thickness, color, and type.
You can also assign a shape to either or both ends of a connector line.
For example, to indicate the direction of the connection.

ℹ️ Note:

  • When creating connector lines programmatically, either with the Web SDK or the REST API, it's not yet possible to create loose (both ends disconnected) or dangling (one end disconnected) connectors.
    You must specify the x and y coordinates of both the start and end points of a connector line.

See also:

Example:

// Create a shape to use as a start point for the connector.
const start = await miro.board.createShape({
  content: 'start',
  x: 4500,
});

// Create a shape to use as an end point for the connector.
const end = await miro.board.createShape({
  content: 'end',
  x: 4800,
});

// Create a connector line.
const connector = await miro.board.createConnector({
  shape: 'elbowed',
  style: {
    startStrokeCap: 'diamond',
    endStrokeCap: 'stealth',
    strokeStyle: 'dashed',
    strokeColor: '#ff00ff', // Magenta
    strokeWidth: 2,
  },
  // Set the start point of the connector line.
  start: {
    // Define the start board item for the connector line by specifying the 'start' item ID.
    item: start.id,
    // Set a point on the border of the 'start' shape to mark the start point of the connector line.
    position: {
      // Horizontal: right
      x: 1.0,
      // Vertical: middle
      y: 0.5,
    },
  },
  // Set the end point of the connector line.
  end: {
    // Define the end board item for the connector line by specifying the 'end' item ID.
    item: end.id,
    // Set a point on the border of the 'end' shape to mark the end point of the connector line.
    position: {
      // Horizontal: left
      x: 0.0,
      // Vertical: bottom
      y: 1.0,
    },
  },
});

/* Remove the 'end' shape item.
 * The connector is automatically removed as well, because the operation removes also
 * one of the terminal points of the connector line.
 */
const removeEndShape = async () => {
  await miro.board.viewport.zoomTo(connector);
  setTimeout(async () => {
    await miro.board.remove(end);
  }, 3000);
};

await removeEndShape();

Connector example:


Figure 1. The connector line joins the start and end shapes. It starts from the point defined in start.position, and it ends at the point defined in end.position.

Table of contents

Constructors

Properties

Methods

Constructors

constructor

new Connector(props?)

Parameters

NameType
props?ConnectorProps

Properties

type

Readonly type: "connector"


id

Readonly id: string

Unique ID of the item, assigned automatically upon creation.

Example: 3658432978520043388


origin

origin: "center"

origin marks:

  • The positioning reference point of a board item.
    This is the point used to calculate the x and y coordinates of an item when it's positioned on the board, or when it's a child inside a parent item.
  • The rotation pivot point of a board item that supports rotation.

origin accepts only one value: center.
Any other value throws an error.


parentId

Readonly parentId: null | string

If an item is a child of another item, the child's parentId returns the unique identifier of the corresponding parent item.
If an item has no parent, its parentId is null.

You can use the value to retrieve a tree structure when items are nested inside containers.
For example, sticky notes inside frames.


createdAt

Readonly createdAt: string

Timestamp

Date and time when the item was created.

Format: UTC, ISO 8601.
Includes a trailing Z offset.

Example: 2021-05-18T07:59:01Z


createdBy

Readonly createdBy: string

Miro users are automatically assigned a unique ID.

createdBy contains the ID of the user who created the item.

Example: 3658432978520043388


modifiedAt

Readonly modifiedAt: string

Timestamp

Date and time when the item was last modified.

Format: UTC, ISO 8601.
Includes a trailing Z offset.

Example: 2021-05-18T07:59:01Z


modifiedBy

Readonly modifiedBy: string

Miro users are automatically assigned a unique ID.

modifiedBy contains the ID of the user who applied the most recent edit to the item.

Example: 3658432978520043388


shape

shape: ConnectorShape = 'curved'

shape

Sets the shape of the line for the connector item.
Possible values:

  • straight: the line is completely straight.
  • elbowed: the line isn't straight. It bends at 90 degree angles.
  • curved: the line isn't straight. It bends in smooth curves.

Default: curved


Figure 1. Visual representation of straight, elbowed, and curved line shapes.


start

start: undefined | { item: string ; position?: { x: number ; y: number } }

The start object groups properties that define:

  • The board item that the start point of the connector line attaches at.
    To define the start board item, you must specify the item ID.
  • The x and y coordinates that mark the start point of the connector line on the board item area.

ℹ️ Note:

  • The default value is undefined.
    However, you must specify a start and an end for the connector line.
  • When creating connector lines programmatically, either with the Web SDK or the REST API, it's not yet possible to create loose (both ends disconnected) or dangling (one end disconnected) connectors.
    You must specify the x and y coordinates of both the start and end points of a connector line.

start data structure:

start: {
    // Define the start board item for the start point of the connector line
    // by specifying the item ID.
  item: '3458764511234567896',
  position: {
      // x: 0.0 = left; x: 0.5 = center; x: 1.0 = right
        x: 1.0,
      // y: 0.0 = top; y: 0.5 = center; y: 1.0 = bottom
      y: 0.0
  }
}

item

The start or end item that each connector line cap is attached to.
To define start and end board items of a connector line, you specify the ID of the corresponding items.

Example:

item: '3458764511234567890';

position

The position object is nested inside the start and end objects.
It groups the x and y coordinates that mark the start and end points of the connector line.

You must specify the x and y coordinates of both the start and end points of a connector line.
x and y accept numerical values between 0.0 and 1.0 included.

For reference, these are the x and y coordinates that define top-left, center, and bottom-right positions to mark the start or end point of a connector line:

  • x: 0.0, y: 0.0 = top-left corner of the border of the start or end shape.
  • x: 0.5, y: 0.5 = center of the start or end shape.
  • x: 1.0, y: 1.0 = bottom-right corner of the border of the start or end shape.

position data structure:

position: {
  // x: 0.0 = left; x: 0.5 = center; x: 1.0 = right
  x: 1.0,
    // y: 0.0 = top; y: 0.5 = center; y: 1.0 = bottom
    y: 0.0
}


Figure 1. Visual representation of horizontal and vertical reference coordinates.

x

The x-axis coordinate of the start or end point of a connector line.
x accepts numerical values between 0.0 and 1.0 included.

For reference, these are the x coordinates that define horizontal left, center, and right positions to mark the start or end point of a connector line:

  • x: 0.0 = left
  • x: 0.5 = center
  • x: 1.0 = right

y

The y-axis coordinate of the start or end point of a connector line.
y accepts numerical values between 0.0 and 1.0 included.

For reference, these are the y coordinates that define vertical top, middle, and bottom positions to mark the start or end point of a connector line:

  • y: 0.0 = top
  • y: 0.5 = middle
  • y: 1.0 = bottom

end

end: undefined | { item: string ; position?: { x: number ; y: number } }

The end object groups properties that define:

  • The board item that the end point of the connector line attaches at.
    To define the end board item, you must specify the item ID.
  • The x and y coordinates that mark the end point of the connector line on the board item area.

ℹ️ Note:

  • The default value is undefined.
    However, you must specify a start and an end for the connector line.
  • When creating connector lines programmatically, either with the Web SDK or the REST API, it's not yet possible to create loose (both ends disconnected) or dangling (one end disconnected) connectors.
    You must specify the x and y coordinates of both the start and end points of a connector line.

end data structure:

end: {
  // Define the end board item for the end point of the connector line
  // by specifying the item ID.
  item: '3458764511234567890',
  position: {
    // x: 0.0 = left; x: 0.5 = center; x: 1.0 = right
    x: 1.0,
    // y: 0.0 = top; y: 0.5 = center; y: 1.0 = bottom
    y: 0.0
  }
}

item

The start or end item that each connector line cap is attached to.
To define start and end board items of a connector line, you specify the ID of the corresponding items.

Example:

item: '3458764511234567890';

position

The position object is nested inside the start and end objects.
It groups the x and y coordinates that mark the start and end points of the connector line.

You must specify the x and y coordinates of both the start and end points of a connector line.
x and y accept numerical values between 0.0 and 1.0 included.

For reference, these are the x and y coordinates that define top-left, center, and bottom-right positions to mark the start or end point of a connector line:

  • x: 0.0, y: 0.0 = top-left corner of the border of the start or end shape.
  • x: 0.5, y: 0.5 = center of the start or end shape.
  • x: 1.0, y: 1.0 = bottom-right corner of the border of the start or end shape.

position data structure:

position: {
  // x: 0.0 = left; x: 0.5 = center; x: 1.0 = right
  x: 1.0,
    // y: 0.0 = top; y: 0.5 = center; y: 1.0 = bottom
    y: 0.0
}


Figure 1. Visual representation of horizontal and vertical reference coordinates.

x

The x-axis coordinate of the start or end point of a connector line.
x accepts numerical values between 0.0 and 1.0 included.

For reference, these are the x coordinates that define horizontal left, center, and right positions to mark the start or end point of a connector line:

  • x: 0.0 = left
  • x: 0.5 = center
  • x: 1.0 = right

y

The y-axis coordinate of the start or end point of a connector line.
y accepts numerical values between 0.0 and 1.0 included.

For reference, these are the y coordinates that define vertical top, middle, and bottom positions to mark the start or end point of a connector line:

  • y: 0.0 = top
  • y: 0.5 = middle
  • y: 1.0 = bottom

style

style: Object = {}

startStrokeCap

Sets the shape of the start/head of the connector line.
It accepts values from a list of supported shape types.

Default: none (No shape for the start point of the connector.)

endStrokeCap

Sets the shape of the tail end of the connector line.
It accepts values from a list of supported shape types.

Default: stealth (An arrow shape for the end point of the connector.)

Available stroke cap values and their corresponding left and right shapes on the board:

Stroke capLeftRight
  • none
  • stealth
  • arrow
  • filled_triangle
  • triangle
  • filled_diamond
  • diamond
  • filled_oval
  • oval
  • erd_one
  • erd_many
  • erd_one_or_many
  • erd_only_one
  • erd_zero_or_many
  • erd_zero_or_one

Figure 1. Visual representation of the supported connector line stroke cap values with left and right orientation, respectively.

strokeStyle

Sets the type of line for the connector item.
Possible values:

  • normal: the line is solid.
  • dashed: the line is represented by a series of short dashes.
  • dotted: the line is represented by a series of dots.

Default: normal


Figure 1. Visual representation of normal, dashed, and dotted line types.

strokeWidth

Sets the thickness of the line for the connector item.
It accepts an integer between 1 and 24 included.

  • Min. (thin): 1
  • Max. (thick): 24

Default: 1

strokeColor

Hex value representing the color of the connector item line.

Default: #000000 (black)

Type declaration

NameType
startStrokeCap?StrokeCapShape
endStrokeCap?StrokeCapShape
strokeStyle?StrokeStyle
strokeWidth?number
strokeColor?string

Methods

sync

sync(): Promise<void>

sync propagates to the board any changes to item and tag properties.
After updating the properties of an item or a tag, sync it with the board to:

  • Propagate to the board the changes applied to the item or to the tag.
  • Make the changes visible on the board.

All board items and tags require sync to make any changes to their properties visible on the board.

For more information and examples, see Update and sync item properties.

Example:
(The code example updates a text item using sync.
The same mechanism applies to and works in the same way for all supported board items.)

// Create an item.
// In this case, a text item.
const text = await miro.board.createText({
  content: '<p>This is a piece of text to remind me that I always finish what I ...</p>',
  style: {
    fillColor: 'transparent',
    textAlign: 'left',
  },
  x: 0,
  y: 0,
  width: 450,
  rotation: 0.0,
});

// Update the board item by modifying the values of its properties.
// In the text item case, the updated properties modify content, background color, and rotation of the item.
text.content = 'A fourteneer is "A line that rumbles on like this for being a bit too long."';
text.style.fillColor = '#a9fe65';
text.rotation = 180.0;

// Call 'sync' to make the changed board item properties visible on the board.
await text.sync();

// Output the updated board item to the developer console.
console.log(text);

Example:
(The code example updates a tag using sync.
The same mechanism applies to and works in the same way for all supported board items.)

// Create a tag.
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create a sticky note and attach the tag to it.
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tag: "todo"',
  tagIds: [todo.id],
});
console.log(stickyNote.tagIds); // => ['3074457345627244742']

// Update the tag properties: title and color.
todo.title = "won't fix";
todo.color = 'green';

// Call 'sync' to make the changed tag properties visible on the board.
await todo.sync();

// Output the updated tag to the developer console.
console.log(todo);

Returns

Promise<void>