DocumentationResourcesMarketplaceCommunity
Documentation
Build your app

Reference

A reference with an overview of the arguments of the miroBoardsPicker.open method: what they are, what values they accept, and how to pass them when using the method.

Integrating Miro’s BoardsPicker into your website enables site users to collaborate and share ideas with Miro boards in real time. BoardsPicker enables users to embed and share the details of their boards on your website for free, without the need for authentication protocols, such as Open Authorization (OAuth) or APIs.

To get an idea of the possibilities, have a look at the Embed Miro section on the Miro Marketplace.

BoardsPicker reference

The BoardsPicker component has a core method: miroBoardsPicker.open.
This reference gives an overview of the arguments that the miroBoardsPicker.open method can take: what they are, what types and values they accept, what they do, and how to pass them when using the method.

The miroBoardsPicker.open method takes a single argument: options.
The options object has the following properties:

clientId

(required)

The unique Client ID of the app that requests user authorization.
To obtain an app client ID:

  1. In Miro, go to your apps.
  2. In the Created apps section, click the app that you want to obtain the client ID for.
    The client ID is displayed in the App Credentials section.

Example:

clientId: "3074451123581321347"

action

(required)

Defines the way in which BoardsPicker enables selecting and sharing a board when it's embedded in a website.
Allowed options:

Example:

action: "select", // Or: "access-link"

select

action: "select" enables selecting a board to share and embed it on a website.
If the request is successful, the function passed to the success property returns JSON-formatted details of the board selected with the BoardsPicker component.

Example response:

selectedBoard = {
    "id":"uXjVOD9zD_k=",
    "name":"Demo App",
    "viewLink":"https://miro.com/app/board/uXjVOD9zD_k="
}

id is the unique identifier of the selected board.

  • name is the human-friendly name of the board.
  • viewLink is a URL link to the selected board.
    You can pass it to an iframe to embed the board on a website.

For more information about the response to a call with action: "select", see Response for action: 'select'.

access-link

action: "access-link" enables selecting an access level to the embedded board that's being shared.
The selected access level applies to all users accessing the embedded board, regardless of their individual, specific user access rights.

If action is set to access-link, the BoardsPicker response includes the same properties that the select action type returns, as well as the accessLink, accessLinkPolicy, and embedHtml additional properties:

selectedBoard = {
    "id":"uXjVOD9zD_k=",
    "name":"Demo App",
    "viewLink":"https://miro.com/app/board/uXjVOD9zD_k=...",
    "accessLink":"https://miro.com/app/live-embed/...",
    "accessLinkPolicy":"EDIT",
    "embedHtml":"<iframe class=\"miro-embedded-board\" src=\"https://miro.com/app/..."></iframe>"
}

accessLink defines the URL link pointing to the selected board.

  • accessLinkPolicy sets the user access level for the shared embedded board.
    Allowed values, from most to least restricted:
    • private
    • comment
    • view
    • edit
  • embedHtml is an iframe element that enables linking to the selected board so that you can embed it directly into your website.
    This iframe element must include the miro-embedded-board CSS class.

For more information about the response to a call with action: "access-link", see Response for action: 'access-link'.

success

(required)

success takes a callback function as an argument. The callback executes when a user successfully completes a board selection and sharing operation with BoardsPicker.
When a user selects a board, and they successfully complete an interaction with BoardsPicker, the callback returns the details of the specified board.

Example:

success: function(selectedBoard) {
  console.log(selectedBoard)
},

cancel

(optional)

cancel takes a callback function as an argument. The callback executes when a user cancels the BoardsPicker interaction, without completing the operation.
When a user cancels the operation, they close the BoardsPicker component without selecting a board.

Example:

cancel: function() {
  // Do something
},

error

(optional)

error takes a callback function as an argument. The callback executes when a user cannot successfully complete a board selection and sharing operation with BoardsPicker.
This scenario can occur when BoardsPicker encounters an issue that prevents users from successfully completing the interaction, and the operation throws an error.

Example:

error: function(err) {
  console.log(err)
  // Do something...
},

iframeContainer

(optional)

iframeContainer enables opening BoardsPicker in the specified HTML container element.
It can take one of the following values:

  • The ID of the item containing BoardsPicker.
    Pass the ID value as a string.
  • The instance of the HTMLElement containing BoardsPicker.

ℹ️ Note:

  • Define either iframeContainer, or windowRef.
    You cannot use both at the same time.

Example:

function onClick() {
  miroBoardsPicker.open({
    clientId: '...',
    iframeContainer: 'myContainer', // HTMLElement or item ID.
    // ... Other parameters
  })
}

windowRef

(optional)

windowRef enables opening BoardsPicker in the specified open window instance.
You first need to open the target window, and then you can set it as a container for BoardsPicker.
windowRef works only if iframeContainer isn't used.

ℹ️ Note:

  • Define either iframeContainer, or windowRef.
    You cannot use both at the same time.

Example:

function onClick() {
  // Calculate dimensions and position of the pop-up window.
    const pos = {left, top}
    const size = {width, height}
  
    const windowRef = window.open(
      '',
      '_blank',
 `width=${size.width},height=${size.height},left=${pos.left},top=${pos.top},menubar=0,toolbar=0,location=0,personalbar=0,status=0`
    )
    
  miroBoardsPicker.open({
    clientId: '...',
    windowRef: windowRef, // Provide the reference of the container window.
    // ... Other parameters
  })
}

allowCreateAnonymousBoards

(optional)

If allowCreateAnonymousBoards: true, it allows unregistered users to create and interact with a new temporary Miro board.
When it's set to true, you must also pass a valid access token with getToken.

Example:

function onClick() {
  miroBoardsPicker.open({
    clientId: '...', // 1) Put your 'clientId' here.
    action: 'access-link',
    allowCreateAnonymousBoards: true, //2) Enable this option 
    getToken: () => getTokenFromServer(), // Provide token in async way
    success: data => {
      console.log('on success', data)
      document.querySelector('#container').innerHTML = data.embedHtml
    },
    
    error: e => {
      console.log('on error', e)
    },
    
    cancel: () => {
      console.log('on cancel')
    },
    
    windowRef: windowRef, // Link to an open popup window 
  })
}

getToken

(required if allowCreateAnonymousBoards: true. Otherwise, optional)

When using temporary boards, you must provide a JSON Web Token (JWT) from your application’s backend to the BoardsPicker component.

Example:

// Type: () => Promise<string>
function getTokenFromServer() {
  //Get JWT token from your server. Read more about JWT https://jwt.io/
  return fetchPost('https://example.com/token-for-integration-with-miro')
}

🚧

If your website has a policy for blocking Referer information, boards embedded with the access-link action type don’t load.
To solve the issue, you can override the referrerpolicy attribute inside the iframe HTML element on your site.

Example:

<iframe src="https://miro.com/app/..." referrerpolicy="no-referrer-when-downgrade"></iframe>

See also

Updated about 1 year ago

What's next

Explore the Live Embed tutorials and start embedding Miro boards.