Shape

Shape

Represents a geometric shape on a board.
Shapes are useful when drawing flowcharts and diagrams.

When creating or updating a shape item, you can define its dimensions in the following way:

Set or update only width.
Default width: 100 dp
Set or update onlyheight.
Default height: 100 dp
Set or update width and height at the same time.

Example:

const shape = await miro.board.createShape({
  content: '<p>This is a star shape.</p>',
  shape: 'star',
  style: {
    color: '#ff0000', // Default text color: '#1a1a1a' (black)
    fillColor: '#ffff00', // Default shape fill color: transparent (no fill)
    fontFamily: 'arial', // Default font type for the text
    fontSize: 14, // Default font size for the text, in dp
    textAlign: 'center', // Default horizontal alignment for the text
    textAlignVertical: 'middle', // Default vertical alignment for the text
    borderStyle: 'normal', // Default border line style
    borderOpacity: 1.0, // Default border color opacity: no opacity
    borderColor: '#ff7400', // Default border color: '#ffffff` (white)
    borderWidth: 2, // Default border width
    fillOpacity: 1.0, // Default fill color opacity: no opacity
  },
  x: 0, // Default value: center of the board
  y: 0, // Default value: center of the board
  width: 200,
  height: 200,
});

// Output the created item to the developer console
console.log(shape);

Shape item (star shape):

Shape item example: a star shape.
Figure 1. Shape item example: a star shape.

Properties

Methods

Properties

type

• Readonly type: "shape"

Defines the type of item.
Item type is useful to retrieve specific items from a board. For example, you can fetch all card and shape items from the board, and then carry out an action on them.

Example:

// Get all items from the board
const items = await miro.board.get();

// Count all card and shape items on the board
let cards = 0;
let shapes = 0;

items.forEach((items) => {
  switch (items.type) {
    case 'card':
      cards++;
    case 'shape':
      shapes++;
  }
});

// Output to the console the total amount of card and shape items
console.log(`The current board has ${cards} cards and ${shapes} shapes.`);

Overrides

BaseItem.type

width

• Readonly width: number

Width of the item in dp.

See also:

Pixels and dimensions

height

• Readonly height: number

Height of the item in dp.

See also:

Pixels and dimensions

rotation

• rotation: number

Rotation angle of an item in degrees, relative to the board.
You can rotate items clockwise (right) and counterclockwise (left) by specifying positive and negative values, respectively.

The rotation property doesn't perform a rotation action on an item; it assigns the item a rotation angle.
Invoking the same rotation value multiple times on an item re-applies the same value; it doesn't result in multiple rotations of the item.

content

• content: string = ''

The text that you want to display on the shape item.
The text must be shorter than 6000 characters.

content supports plain text, and the following HTML tags:


<a>





<s>

Unsupported HTML tags are automatically escaped. Therefore, in the shape item on the board they're rendered as plain text literals, instead of HTML output.

shape

• shape: "rectangle"

The visual shape of the item displayed on a board.

Basic shapes

Basic geometric shapes, such as circle, square, rectangle, and so on.

The Miro Web SDK supports the following basic shapes:

Value	Shape on the board UI
`rectangle`
`round_rectangle`
`circle`
`triangle`
`rhombus`
`parallelogram`
`trapezoid`
`pentagon`
`hexagon`
`octagon`
`wedge_round_rectangle_callout`
`star`
`flow_chart_predefined_process`
`cloud`
`cross`
`can`
`right_arrow`
`left_arrow`
`left_right_arrow`
`left_brace`
`right_brace`

Default: rectangle

style

• style: Object

The style object groups properties that define the layout, the look and feel of specific elements of an item, when it's displayed on the board.
For example: background color, font family, font type, horizontal and vertical alignment of the text, text color, and so on.

The Miro Web SDK doesn't support all standard style, yet. Additional styles will be included in future releases.

style data structure:

style: {
  color: '#ff0000', // Default text color: '#1a1a1a' (black)
  fillColor: '#ffff00', // Default shape fill color: transparent (no fill)
  fontFamily: 'arial', // Default font type for the text
  fontSize: 14, // Default font size for the text, in dp
  textAlign: 'center', // Default horizontal alignment for the text
  textAlignVertical: 'middle', // Default vertical alignment for the text
  borderStyle: 'normal', // Default border line style
  borderOpacity: 1.0, // Default border color opacity: no opacity
  borderColor: '#ff7400', // Default border color: '#ffffff` (white)
  borderWidth: 2, // Default border width
  fillOpacity: 1.0, // Default fill color opacity: no opacity
},

`color`

Hex value representing the color of the text string assigned to the the content property of the board item.

Default: #1a1a1a (black)

`fillColor`

Hex value representing the color that fills the area of the text item.

Default: transparent (no fill color)

`fillOpacity`

fillOpacity works similarly to the opacity property in CSS.
It sets the opacity level of the background fill color defined in the fillColor property of the board item.

Allowed values: any number between 0.0 and 1.0 included.

If the value is 0.0, the background fill color is completely transparent or invisible.
If the value is 1.0, the background fill color is completely opaque or solid.

Default: 1 (solid color, no opacity)

`fontFamily`

Sets the type of font for the text in the content property of the shape item.

Possible font families:

arial
cursive
abril_fatface
bangers
eb_garamond
georgia
graduate
gravitas_one
fredoka_one
nixie_one
open_sans
permanent_marker
pt_sans
pt_sans_narrow
pt_serif
rammetto_one
roboto
roboto_condensed
roboto_slab
caveat
times_new_roman
titan_one
lemon_tuesday
roboto_mono
noto_sans
plex_sans
plex_serif
plex_mono
spoof
tiempos_text
noto_serif
noto_serif_jp
noto_sans_jp
noto_sans_hebrew
noto_serif_sc
noto_serif_kr
noto_sans_sc
noto_sans_kr
serif
sans_serif
monospace

Default: arial

`fontSize`

Defines the font size, in dp, for the text in the content property of the shape item.

Default: 14

`textAlign`

Sets the horizontal alignment of any text in the content property of the shape item.

Possible values:

left: the text is aligned with the left margin of the text area.
center: the text is at an equal distance from the left and right margins of the text area.
right: the text is aligned with the right margin of the text area.

Default: center

`textAlignVertical`

Sets the vertical alignment of any text in the content property of the shape item.

Possible values:

top: the text is aligned with the top margin of the text area.
middle: the text is at an equal distance from the top and bottom margins of the text area.
bottom: the text is aligned with the bottom margin of the text area.

Default: middle

`borderStyle`

Sets the type of line that defines the boundaries of the shape 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.

`borderOpacity`

borderOpacity works similarly to the opacity property in CSS.
It sets the opacity level of the color of the line that defines the boundaries of the board item, and that delineates its shape.
The borderColor property defines the color of the line.

Allowed values: any number between 0.0 and 1.0 included.

If the value is 0.0, the border line color is completely transparent or invisible.
If the value is 1.0, the border line color is completely opaque or solid.

Default: 1 (solid color, no opacity)

`borderColor`

Hex value representing the color of the line that defines the boundaries of the board item.

Default: #ffffff (white)

`borderWidth`

Sets the thickness of the line that defines the boundaries of the board item.
It accepts an integer between 0 and 24 included.

Min.: 0 (no border line)
Max.: 24 (thick border line)

Default: 2

Type declaration

Name	Type
`color`	`string`
`fillColor`	`string`
`fillOpacity`	`number`
`fontFamily`	`FontFamily`
`fontSize`	`number`
`textAlign`	`TextAlign`
`textAlignVertical`	`TextAlignVertical`
`borderStyle`	`StrokeStyle`
`borderOpacity`	`number`
`borderColor`	`string`
`borderWidth`	`number`

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.

relativeTo

• relativeTo: RelativeTo

The relativeTo property affects the x and y coordinate values of a board item.
relativeTo defines the positioning reference of a board item, which can be:

Depending on whether an item is a child of a parent item or not, relativeTo can have one of the following values:

Value	Description	On the board UI
`canvas_center`	The item is positioned on the board, and it's not a child of another item. The `x` and `y` coordinate values of the item are relative to the center of the board.	Figure 1. The `relativeTo` property of the board item—a sticky note in the example image—is set to `canvas_center`. The same mechanism applies to and works in the same way for all supported board items.
`parent_top_left`	The item is positioned on the board, and it is a child of a parent item. For example, a parent frame. The `x` and `y` coordinate values of the child item are relative to the top-left corner of the parent item).	Figure 2. The `relativeTo` property of the board item—a sticky note in the example image—is set to `parent_top_left`. The same mechanism applies to and works in the same way for all supported board items.
`parent_center`	Experimental feature The item is positioned on the board, and it is a child of a parent mind map node. The `x` and `y` coordinate values of the item are relative to the center of the parent mind map node item.	Figure 3. The `relativeTo` property of the child mind map nodes is set to `parent_center`.

See also:

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 or text items inside mindmaps.

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

ℹ️ Note:

Timestamps indicating creation and update times are always in UTC time, regardless of the time offset configured on the machine where the app runs or where the code is executed.

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

ℹ️ Note:

Timestamps indicating creation and update times are always in UTC time, regardless of the time offset configured on the machine where the app runs or where the code is executed.

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

x

• x: number

The x-axis coordinate of an item is the horizontal distance in dp of the center point of the item from the center point of the board.

The center point of the board has x: 0 and y: 0 coordinates.

Default: 0

See also:

y

• y: number

The y-axis coordinate of an item is the vertical distance in dp of the center point of the item from the center point of the board.

The center point of the board has x: 0 and y: 0 coordinates.

Default: 0

See also:

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>

getMetadata

▸ getMetadata(): Promise<AppData>

Experimental

Fetches board item metadata, stored per app, for the specified metadata key.
The response contains the metadata value assigned to the requested key.

To fetch all the metadata for a board item, invoke the method without passing any arguments.
The response contains all the metadata associated with the board item as key/value pairs.

An app can access only the metadata that it sets.
It cannot access metadata set by other apps.

getMetadata and setMetadata are available for the following board items:

Card
Connector
Embed
Image
Preview
Shape
Sticky note
Text

The methods aren't available for the following board items:

Frames
Unsupported board items

ℹ️ Note:

To access board item metadata, apps require the boards:read permission.
To store board item metadata, apps require the boards:write permission.
getMetadata returns a new object, not a reference to the object that was previously set with setMetadata.
If the specified key isn't found, the method returns undefined.

⚠️ Warning:

Use AppMetadata to store limited amounts of metadata.
Recommended: < 6 KB.
When updating metadata, limit the data size of the update payload.
Recommended: < 6 KB.
Don't use AppMetadata as a file storage solution (< 300 KB).

Example:

// Get the board item you want to retrieve metadata from.
const [geoCard] = await miro.board.get({type: 'card'});

// Set item metadata for an imaginary geocaching game, and store it to the retrieved card item.
await geoCard.setMetadata('leaderboard', ['Ziltoid', 'Howard', 'Paul']);

// Get the specific 'leaderboard' metadata from the card item.
const leaderboard = await geoCard.getMetadata('leaderboard');

// Get all the metadata from the card item by passing no arguments.
await geoCard.getMetadata();

Returns

Promise<AppData>

▸ getMetadata<T>(key): Promise<T>

Type parameters

Name	Type
`T`	extends `AppDataValue`

Parameters

Name	Type
`key`	`string`

Returns

Promise<T>

setMetadata

▸ setMetadata<T>(key, value): Promise<T>

Experimental

Adds board item metadata to make it available on the board that the app runs on.
An app can access only the board item metadata that it sets.
It cannot access metadata set by other apps.

Board item metadata is stored in the item it refers to. Therefore:

When duplicating an item, the metadata is copied to the new item.
When deleting an item, the corresponding metadata is removed with the deleted item.

Board item metadata is synced across, and available to, all the users who can:

Access and view the board that the app is running on, AND
Run the app on the board.

AppMetadata is a key/value-pair object. It can contain values with the following data types:

string
number
boolean
Object
Array

getMetadata and setMetadata are available for the following board items:

Card
Connector
Embed
Image
Preview
Shape
Sticky note
Text

The methods aren't available for the following board items:

Frames
Unsupported board items

ℹ️ Note:

To access board item metadata, apps require the boards:read permission.
To store board item metadata, apps require the boards:write permission.
You can overwrite the value of an existing key inside AppMetadata: if you pass the same key multiple times with different values, only the last/most recent value is stored with the key.
After setting a key, you cannot delete it; you can only update it.
However, you can delete the corresponding value by setting it to null, or to an empty value ('').
You can assign an empty array ([]) as the value of a key. It's returned as an empty array.

⚠️ Warning:

Use AppMetadata to store limited amounts of metadata.
Recommended: < 6 KB.
When updating metadata, limit the data size of the update payload.
Recommended: < 6 KB.
Don't use AppMetadata as a file storage solution (< 300 KB).

Example:

// Get the board item you want to set metadata to.
const [geoCard] = await miro.board.get({type: 'card'});

// Set item metadata for an imaginary geocaching game, and store it to the retrieved card item.
await geoCard.setMetadata('geoData', {
  name: 'null',
  coordinates: {
    latitude: '33.950278',
    longitude: '-105.314167',
  },
  lastFound: '1947-07-08',
  content: true,
  difficulty: 5,
  keywords: ['x-files', 'truth-is-out-there', 'area-51', 'roswell', 'aliens'],
  geoCache: [
    {
      name: 'UFO',
      description: 'Severely damaged unidentified flying object. ',
    },
    {
      name: 'Alien',
      description: 'Remains of an alien life form.',
    },
    {
      name: 'Artifacts',
      description: 'Tools, equipment, and other items found at the crash site.',
    },
    {
      name: 'Edibles',
      description: 'The alien was likely as high as a kite when they crashed. Typical.',
    },
  ],
});

// Get the specific 'geoData' metadata from the card item.
// The response contains the metadata value assigned to the key.
const geoCardGeoData = await geoCard.getMetadata('geoData');

// Get all the metadata from the card item.
// The response contains all the metadata assigned to the board item as key/value pairs.
const geoCardAllMetaData = await geoCard.getMetadata();

// Clear the metadata about the imaginary geocaching game by assigning 'geoData' an empty object.
await geoCard.setMetadata('geoData', {});

// If the card item metadata has a top-level key, you can clear all the metadata
// from the card item by assigning the top-level key an empty object.
// In this example, the top-level key name is 'metaData'.
await geoCard.setMetadata('metaData', {});

Type parameters

Name	Type
`T`	extends `AppData`

Parameters

Name	Type
`key`	`string`
`value`	`AppDataValue`

Returns

Promise<T>

Table of contents

Properties

Methods

Properties

type

Overrides

width

height

rotation

content

shape

Basic shapes

style

color

fillColor

fillOpacity

fontFamily

fontSize

textAlign

textAlignVertical

borderStyle

borderOpacity

borderColor

borderWidth

Type declaration

id

origin

relativeTo

parentId

createdAt

createdBy

modifiedAt

modifiedBy

x

y

Methods

sync

Returns

getMetadata

Returns

Type parameters

Parameters

Returns

setMetadata

Type parameters

Parameters

Returns

`color`

`fillColor`

`fillOpacity`

`fontFamily`

`fontSize`

`textAlign`

`textAlignVertical`

`borderStyle`

`borderOpacity`

`borderColor`

`borderWidth`