Miro Web SDK Reference Guide v1 -> v2

If your app currently uses the Miro Web SDK v1, it’s time to plan your migration to v2. The Miro Developer Platform 2.0 has reworked and improved the Web SDK, focusing on performance and reliability, as well as the developer experience. This document will outline the changes in certain data objects, and in how those objects relate to others. For a higher-level explanation of these changes, be sure to check out the comparison guide.

window.miro

The window.miro object continues to be the root object of the Web SDK, serving as the main entry point to the SDK methods. All methods in this reference guide are referred to by their hierarchy following window.miro.**___**.

Boards

At first glance, much of the v1 board object has changed. Despite this, working with a board object in the Miro Web SDK v2 should feel familiar. The structure of the board object is fundamentally the same between v1 and v2. While many methods were renamed for improved clarity, they behave in the same manner as in v1.

Creating a widget / item

The most significant change for board objects in the v2 Web SDK is the replacement of the board.widgets.create method with individual constructors for each widget type.

In the Miro Web SDK v1, the widget methods were polymorphic – meaning that one method was used to interact with all potential widget types. The structure of the call would differ depending on what type of widget you were creating or updating. In the v2 SDK, we have replaced this with an independent constructor for each widget type. Widgets are now referred to as "items" and each item exists as its own object, rather than as a property of the board.

The new item constructors should feel familiar to you, as they were designed to mostly follow the structure of the type-specific payloads of the previous board.widgets.create() call. The following table provides a map of the v1 board.widgets.create call for each supported widget type and its equivalent v2 item constructor.

board.createAppCard({
    title: "Hello, app card",
    description: "This is a description"
})

board.widgets.create({
    type: "card", 
    title: "Hello, card"
})

board.createCard({
    title: "Hello, card"
})

board.widgets.create({
    type: "embed", 
    html: "miro.com/blog"
})

board.createEmbed({
    url: "https://www.miro.com/blog"
})

board.widgets.create({
    type: "emoji"
})

board.widgets.create({
    type: "frame", 
    title: "Hello, frame"
})

board.createFrame({
    title: "Hello, frame"
})

board.widgets.create({
    type: "image", 
    title: "Hello, image", 
    url: "miro.com/logo"}
)

board.createImage({
    title: "Hello, image", 
    url: "miro.com/logo"
})

board.widgets.create({
    type: "line", 
    startWidgetId: "[[id]]", 
    endWidgetid: "[[id]]"
})

board.createConnector({
  shape: 'elbowed',
  style: {
    startStrokeCap: 'diamond',
    endStrokeCap: 'stealth',
    strokeStyle: 'dashed',
    strokeColor: '#ff00ff', // Magenta
    strokeWidth: 2,
  },
  start: {
    item: start.id,
    position: {
      x: 1.0,
      y: 0.5,
    },
  },
  end: {
    item: end.id,
    snapTo: 'right',
  },
});

board.createPreview({
    url: "https://miro.com"
})

board.widgets.create({
    type: "shape", 
    text: "Hello, shape",
    style: {
        shapeType: "star"
    }
})

board.createShape({
    content: "Hello, shape",
    shape: "star"
})

board.widgets.create({
    type: "sticker", 
    text: "Hello, world"
})

board.createStickyNote({
    content: "Hello, world"
})

board.widgets.create({
    type: "text", 
    text: "Hello, words"
})

board.createText({
    content: "Hello, words"
})

Board properties

The table below provides a side-by-side comparison of each board property in the v1 and v2 Web SDKs. The majority of the properties supported in v1 have been removed, and so we have tried to provide the reasoning behind those removals.

Board metadata / storage

In the v1 Web SDK, board.metadata supported two experimental methods. Metadata was also sometimes referred to as "storage" and provided developers with a way to write a key-value data object into local storage.

Both of these endpoints have been upgraded and are now fully-supported in v2, and have been renamed for clarity.

• board.metadata.get() is now board.getAppData()
• board.metadata.update() is now board.setAppData()

The table below provides a side-by-side comparison of the usage of each method.

board.metadata.update("key", "value")

board.setAppData("key", value)

board.metadata.get("key")

board.getAppData("key")

V2 also introduces support for item-level metadata. You can now set and get metadata that is associated with a particular item on the board:
setMetadata

board.setMetadata("key", value)

getMetadata

board.getMetadata("key")

Storage collection

In addition to app and item-level metadata, the V2 Web SDK introduces new support for Storage collection. This provide the ability to store, retrieve, and remove data from a specified collection using key value pairs.

Storage collection provides more storage capability than app and item-level metadata offers and enables you to build logic for when certain keys change (onValue listener).

For a full comparison of all supported metadata and storage options in the V2 Web SDK, see the Storage guide.

BoardUI

When building the v2 SDK, we decided to rethink the way we expose extension points. As a result of this design choice, we have removed several extension points that were available in v1.

Currently, developers building applications with the Miro v2 Web SDK have two options available: the app panel ("Panel") and the pop-up modal ("Modal"). The bottom bar and the left sidebar are no longer available.

The table below shows the board.ui endpoints from v1 and their v2 counterparts, if available.

board.ui.openLibrary(
    "show-this-page-in-the-library.html", 
    { title: "The library!" }
)

board.ui.openPanel({
    url: 'show-this-page-in-the-panel.html'
})

board.ui.closeLibrary()

board.ui.closePanel()

board.ui.openModal(
    "show-this-page-in-the-modal.html", 
    { 
        width: 400, 
        height: 400 
    }
)

board.ui.openModal({
    url: 'show-this-page-in-the-modal.html',
    width: 600,
    height: 400,
    fullscreen: false,
})

board.ui.closeModal()

board.ui.closeModal()

board.ui.openLeftSidebar(
    "show-this-page-in-the-sidebar.html"
)

board.ui.closeLeftSidebar()

board.ui.openBottomPanel(
    "show-this-page-in-the-bottom-bar.html", 
    {
        width: 200,
        height: 200,
    }
)

board.ui.closeBottomPanel()

V2 also introduces additional helper methods for understanding if modals or panels already open on a board. You can now check modal and panel statuses:
canOpenModal

board.ui.canOpenModal()

canOpenPanel

board.ui.canOpenPanel()

V2 also introduces new methods in board.ui for manager the Z-index of an item. See getLayerIndex and its associated methods for more details on managing layers (Z-index) for items.

Events

The V2 Web SDK introduces new support for events which can be used trigger certain logic in an app. Events capture user actions, board changes, and more—enabling your app to respond to actions in Miro.

The V2 Web SDK supports events for:

• Board UI
• Collaboration
  • Session
• Storage collection
• Timer
• Realtime
  • Note: Realtime events are created and sent by the app developer

For more details on supported events, see the Events guide for a comparison between each type of supported event.

Viewport

In both the v1 and v2 Web SDKs, board.viewport serves as the namespace for the collection of methods that interact with the current viewport. The viewport endpoints are largely unchanged, with one major exception: the three methods for controlling the zoom level of a viewport in v1 are no longer supported in v2.

See the table below for a full side-by-side comparison of each board.viewport method and its usage across both v1 and v2.

board.viewport.get()

board.viewport.get()

board.viewport.getViewport()

board.viewport.get()

board.viewport.set({
    x: x-coordinate,
    y: y-coordinate,
    height: height-of-viewport,
    width: width-of-viewport
})

board.viewport.set({
    x: x-coordinate,
    y: y-coordinate,
    height: height-of-viewport,
    width: width-of-viewport
})

board.viewport.zoomToObject(myShape.id)

board.viewport.zoomTo(myShape)

board.viewport.setViewportWithAnimation(
    viewport: {
        x: x-coordinate,
        y: y-coordinate,
        height: height-of-viewport,
        width: width-of-viewport
    },
    animationTimeInMs: 1000
)

board.viewport.set(
    viewport: {
        x: x-coordinate,
        y: y-coordinate,
        height: height-of-viewport,
        width: width-of-viewport
    },
    animationDurationInMs: 1000
)

board.viewport.setZoom(percentage)

board.viewport.setZoom(integer)

board.viewport.getZoom()

board.viewport.getZoom()

board.viewport.getScale()

Widgets / Items

In the Miro Web SDK v1, the widget methods were polymorphic – meaning that one method was used to interact with all potential widget types. The structure of the call would differ depending on what type of widget you were creating or updating. In the v2 SDK, we have replaced this with independent endpoints for each item type. Widgets are now referred to as "items" and each item exists as its own object, rather than as a property of the board object.

widgets.update() and the new sync() method

Every item type has a sync() method. All item updates are now handled through [item].sync() rather than board.widgets.update(). For more information on the sync() method and an explanation of its usage, please refer to this guide.

The following table shows an example of updating the title of a card item in both v1 and v2.

board.widgets.update({
    id: myCard.id,
    title: "New Card Title"
})

myCard.title = "New Card Title"
myCard.sync()

board.widgets endpoints

With the removal of the board.widgets property in the v2 Web SDK, the methods contained in the boards.widget namespace have moved to the board object in v2. The board.widgets.create() and board.widgets.update() methods are discussed separately in this guide, but the remaining methods can be found in the table below, side-by-side with their v2 counterparts.

board.widgets.get()

board.get()

board.getById()

board.widgets.bringForward(myWidget.id)

board.bringToFront(myItem)

board.widgets.sendBackward(myWidget.id)

board.sendToBack(myItem)

board.widgets.deleteById(myWidget.id)

board.remove(myItem)

board.widgets.images.get()

board.get({
    type: image
})

board.widgets.areAllWidgetsLoaded()

board.widgets.transformDelta()

Widget / Item properties

In the v2 Web SDK, each item type has its own defined set of properties, directly applicable to that item. These properties would include data unique to the item, such as the type of shape, or style options like color choices. Other properties are universal to all item types, such as geometry or positioning information.

The table below enumerates the various item properties as they exist in both v1 and v2, beginning with the universal properties, and then moving into type-specific properties.

"Unsupported" item types

For board items that are not yet supported in the Miro v2 Web SDK, there is an unsupported item type, which serves as a catch-all object. It does not offer any item-specific properties, but it does have a sync() method. This allows applications to interact with unsupported board objects, including moving or relocating these objects.

Currently, the following item types are not yet supported in the v2 SDK.

• Comment
• Curve
• Document
• Emoji
• Mockup
• Web Screenshot

We will be adding new item types over time, and we will continue to share updates as we make progress. There are several feature requests already noted on our roadmap, and we encourage you to add your votes and subscribe to future updates. You’re also welcome to raise any questions or concerns in our developer Discord or on our community forum.

Tags

As with the v1 board.widgets property, board.tags is no longer a supported property in the v2 SDK. Tags now exist as their own object, rather than as a property of the board object.

Creating a tag

Although tags are not considered to be items on a Miro board, the new item constructor approach has also been used to create a tag constructor. A side-by-side comparison of the v1 and v2 constructions can be found in the table below.

board.tags.create({
    title: "Hello, tag", 
    color: "yellow"
})

board.createTag({
    title: "Hello, tag", 
    color: "yellow"
})

Updating a tag

Similar to items, tag objects each have a sync() method. All tag updates are now handled through [tag].sync() rather than board.tags.update(). For more information on the sync() method and an explanation of its usage, please refer to this guide.

The following table shows an example of updating a tag in both v1 and v2.

board.tags.update({
    id: myTag.id,
    title: "New Tag Title"
})

myTag.title = "New Tag Title"
myTag.sync()

Working with tags

Aside from the new create and update implementations, tags are similar across the v1 and v2 SDKs. The most significant change lies in how tags and items are associated. In the v1 Web SDK, a tag was assigned to a widget by adding the widget’s ID to the tag object. In the v2 Web SDK, this has been reversed to the more intuitive approach, where a tag’s ID is added to an item object.

For this, and other side-by-side comparisons of tags across v1 and v2, see the table below.

board.tags.get()

board.get({type: "tag"})

board.tags.delete(myTag.id)

board.remove(myTag)

Info

In the Miro v1 Web SDK, board.info served as the namespace for methods related to getting board information. However, there was only one supported method in this namespace: board.info.get().
This has been removed in v2, as there is not a need for a dedicated namespace for board information.

Board information can now be retrieved using the board.getInfo() method, as shown in the table below. Unfortunately, the v2 board info object is pretty bare compared to its v1 counterpart. This is a known issue, and the board info objects have been included in the table below for clarity.

board.info.get()

board.getInfo()

Selection

In the v1 Web SDK, board.selection served as the namespace for methods that interacted with the selection of certain widgets on the board. In v2, the equivalent methods are board.getSelection, board.select, and board.deselect.

The table below provides a side-by-side comparison of the v1 board.selection property and its v2 counterpart (if available).

board.selection.get()

board.getSelection()

board.enterSelectWidgetsMode()

board.selection.selectWidgets(myWidget.id)

board.select(myWidget.id)

board.selection.clear()

board.deselect(myWidget.id)

Utils

In the v1 Miro Web SDK, board.utils served as the namespace for utility methods for a board. This property has been removed in v2, as there is not a need for a dedicated namespace for board utility functions.

Specifically, in the v1 SDK, there was only one supported method in this namespace: board.utils.unionWidgetBounds(). With v2, the bounds object is no longer a property of board items, rendering the sole utility method obsolete.

board.utils.unionWidgetBounds()

The V2 Web SDK has, however, started to introduce some similar utility-type methods, such as findEmptySpace. This method can be accessed from the experimental namespace, and allows you to programmatically find empty space on a Miro board when positioning items. See findEmptySpace.

Users and Accounts

The v1 Web SDK offered several endpoints for working with users and accounts, including the UserInfo object, Account Info object, and several methods, including:

• .account.get()
• .currentUser.getScopes()
• .currentUser.isSignedIn()
• .currentUser.getCurrentBoardPermissions()
• .currentUser.getCurrentAccountPermissions()
• .currentUser.isMemberOfCurrentAccount()

None of these are available in the Miro v2 Web SDK. When building the v2 platform, all enterprise methods have been moved to the REST API. The Web SDK will no longer offer any endpoints that require a Team or Organization authorization scope.

However, applications can still retrieve the context and information of the current authenticated user by using board.getUserInfo(). An example of this method, and its v1 counterpart, is provided in the table below.

.currentUser.getId()

board.getUserInfo()

The V2 SDK also introduces a new method to retrieve users who are currently active on a board. See getOnlineUsers.

Additional capabilities in V2

There are several additional capabilities that are now supported in the V2 Web SDK, including:

• Mindmaps
• Collaboration and Session Management
• Storage
• Realtime Events
• Timer
• Group/Ungroup methods
• Additional shape types
• Enhanced image capabilities
  • We now return the URL for all images on the board. This allows developers to download the image and perform other relevant tasks. For more information, see our Web SDK reference documentation on images.
• goToLink and linkedTo methods
• Custom Actions
• Layers (Z-Index)

We will continue to expand support for new capabilities in our V2 Web SDK. Stay up to date with our changelog for the latest developments.

New namespaces in V2

The V2 Web SDK introduces a couple of new namespaces.

Experimental

The experimental namespace, miro.board.experimental, is where certain experimental features or methods will be exposed as an early preview. These methods should not be relied on in a production environment.

Features or methods that are experimental in v2 will be reflected with an experimental tag in the reference documentation.

Collaboration

The collaboration namespace, miro.board.collaboration, is where new features or methods related to collaborative experiences will be exposed. See Collaboration.

V1 experimental methods

Some of the experimental methods from the v1 Web SDK are now fully supported in v2. For those that were not upgraded to become permanent parts of the v2 platform, we have removed the methods from our SDK. This is an attempt to clean up erroneous code, and to ensure a consistent developer experience.

The removed methods are listed below.

• board.__getParamsFromURL()
• board.widgets.__blinkWidget()
• board.widgets.__getIntersectedObjects()
• board.comments.get()

If any of these methods were critical to your v1 application, or if you have any other questions or concerns, please reach out. You can post in our community forum, start a discussion in our developer Discord, or suggest and vote on new features in our public roadmap.