These docs are for v1.0. Click to read the latest docs for v2.0.

boardsPicker Component

How to configure boardsPicker:

1) Create a dev-team and an application.

Detailed instructions are here: https://developers.miro.com/docs/getting-started
You will need your application's client_id to open boardsPicker

1282

2) In the app's settings, provide the domain names where your Boards Picker is hosted. This lets us stop other websites from trying to impersonate your app. If you're developing locally, you can use localhost as the domain name as well.

2000

5) Add the following JavaScript snippet in your HTML.

<script type="text/javascript" src="https://miro.com/app/static/boardsPicker.1.0.js"></script>

<script>
  function onSomeButtonClick() {
    miroBoardsPicker.open({
      clientId: 'client_id_from_your_app',
      action: 'select',
      success: function (result) {
        console.log(result)
      }
    })
  }
</script>

The source code of this demo is here.

🚧

Note that access-links generated in this example can't be used on your site because your site domain must be whitelisted.

Call the miroBoardsPicker.open() method to open the Boards Picker. Note that the Boards Picker opens in a pop-up window. Ensure to call this function from within a user-triggered event (click or tap). Otherwise, the browser blocks the pop-up.

The open method takes a single options parameter with the following fields:

options = {
    // Required. ClientId from your app.
    clientId: 'string', 
  
    // Required. Define mode of Boards Picker.
    action: "select" // or "access-link"
  
    // Required. Called when a user selects a board in the Picker.
    success: function(selectedBoard) {
        console.log(selectedBoard)
    },

    // Optional. Called when the user closes the pop-up.
    cancel: function() {
    },
      
    // Optional. Called when something went wrong.      
    error: function() {
    },

    windowRef: windowRef, // Optional. Link to an already opened popup window. See the example below in case you want lazy loading for boardsPicker.js. 
};

Choosing the action type

The boardsPicker component provides two types of action: select and access-link.

  • select allows the user to choose a board and gives you a response with the board URL; you can use this URL, for example, to generate embed link;
  • access-link allows the user to choose a board and choose an additional level of access for a unique link. With this action, you get a response with the board URL, access-link, and iFrame code that you can use for embedding;

Handling the response.

The success callback returns information about the selected board.

//when the action is 'select'
selectedBoard = {
    id: "o9J_687XKf0="
    name: "Demo board"
    description: "Description for the demo board"
    viewLink: "https://miro.com/app/board/o9J_687XKf0=/"
}

//when the action id is 'acccess-link'
{
	accessLink: "https://miro.com/app/live-embed/o9J_k1ISaY4=?boardAccessToken=5IXCDJzAzw1bR85fJiYbH4WxHoCPTpmV&autoplay=true"
	accessLinkPolicy: "EDIT"
	description: undefined
	embedHtml: "<iframe class=\"miro-embedded-board\" src=\"https://miro.com/app/live-embed/o9J_k1ISaY4=?boardAccessToken=5IXCDJzAzw1bR85fJiYbH4WxHoCPTpmV&autoplay=true\" referrerpolicy=\"no-referrer-when-downgrade\" frameborder=\"0\" style=\"background: transparent; border: 1px solid #ccc;\"></iframe>"
	id: "o9J_k1ISaY4="
	name: "test"
	viewLink: "https://miro/app/board/o9J_k1ISaY4="
}

Enabling your integration for public use

By default, boardsPicker is only available for your Developer Team.

Submit this form when your integration is ready for public use. After submitting the form, you’ll receive an email that will help you get going. In the meantime, we’ll evaluate your request (usually within 24 - 48 hours) and we’ll green-light your clientId for the relevant use cases.

Troubleshooting

If your website has a policy for blocking referrer information, Embeds via access-link does not load. To fix this, you can override the referrerpolicy attribute for the iframe tag on your site.

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