Board UI

if (await miro.board.ui.canOpenPanel()) {
  await miro.board.ui.openPanel({
    url: 'show-this-page-in-the-panel.html',
    height: 400,
  });
}

Promise<{ waitForClose: () => Promise<Result | undefined> }>;

// Example 1: Basic usage of openPanel
await miro.board.ui.openPanel({
  url: 'show-this-page-in-the-panel.html',
});
// The panel is displayed on the board

// Example 2: Passing data into the panel
const dataForModal = "hello world";
await miro.board.ui.openPanel<string>({
  data: dataForModal,
  url: 'show-this-page-in-the-panel.html',
});

// Example 3: Waiting for the panel to close
const someData = { message: "my message" };
const { waitForClose } = await miro.board.ui.openPanel<{message: string}, string>({
  data: someData,
  url: 'show-this-page-in-the-panel.html',
});

// Inside the panel, you can call the following to close the panel and resolve the Promise:
//     await miro.board.ui.closePanel('result');
console.log(await waitForClose()); // This will log: "result"

// Define some data to pass to the panel
const someData = { message: "my message" };

// Open a panel and pass the data to it
const { waitForClose } = await miro.board.ui.openPanel<{message: string}, string>({
  data: someData,
  url: 'show-this-page-in-the-panel.html',
  height: 400,
});

// Retrieve the data from within the panel
const data = await miro.board.ui.getPanelData<{message: string}>()

console.log(data) // Outputs: "{ message: "my message" }"

// Open a panel
await miro.board.ui.openPanel({
  url: 'show-this-page-in-the-panel.html',
  height: 400,
});

// Close the open panel
await miro.board.ui.closePanel();

// Open a panel and wait for the result
const {waitForClose} = await miro.board.ui.openPanel({
  url: 'show-this-page-in-the-panel.html',
  height: 400,
});

async function logResult() {
    const result = await waitForClose();
    console.log(result) // This will log: "Hello world!"
}

logResult()

// Close the open panel with some result
await miro.board.ui.closePanel("Hello world!");

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

Promise<{ waitForClose: () => Promise<Result | undefined> }>;

// Example 1: Basic usage of openModal
await miro.board.ui.openModal({
  url: "show-this-page-in-the-modal.html",
  width: 600,
  height: 400,
  fullscreen: false,
});
// This will open a modal with the specified URL, width, and height. The modal will not be displayed in fullscreen mode.

// Example 2: Passing data into the modal
const dataForModal = "hello world";
await miro.board.ui.openModal<string>({
  data: dataForModal,
  url: "show-this-page-in-the-modal.html",
  width: 600,
  height: 400,
  fullscreen: false,
});

// Example 3: Waiting for the modal to close
const someData = { message: "my message" };
const { waitForClose } = await miro.board.ui.openModal<{message: string}, string>({
  data: someData,
  url: "show-this-page-in-the-modal.html",
  width: 600,
  height: 400,
  fullscreen: false,
});

// Inside the modal, you can call the following to close the modal and resolve the Promise:
//     await miro.board.ui.closeModal('result');
console.log(await waitForClose()); // This will log: "result"

// Define some data to pass to the modal
const someData = { message: "my message" };

// Open a modal and pass the data to it
const { waitForClose } = await miro.board.ui.openModal<{message: string}, string>({
  data: someData,
  url: "show-this-page-in-the-modal.html",
  width: 600,
  height: 400,
  fullscreen: false,
});

// Retrieve the data from within the modal
const data = await miro.board.ui.getModalData<{message: string}>()

console.log(data) // Outputs: "{ message: "my message" }"

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

// Close the open modal
await miro.board.ui.closeModal();

// Open a modal and wait for the result
const {waitForClose} = await miro.board.ui.openModal({
  url: 'show-this-page-in-the-modal.html',
  height: 400,
  width: 600,
  fullscreen: false,
});

async function logResult() {
    const result = await waitForClose();
    console.log(result) // This will log: "Hello world!"
}

logResult()

// Close the open modal with some result
await miro.board.ui.closeModal("Hello world!");

miro.board.ui.on(event, handler);

on(event: 'drop', handler: (event: DropEvent) => void): void

/** When the selected HTML element is dropped on the board:
 *  1. A sticky note is created.
 *  2. The text of the HTML element is assigned to the
 *     'content' property of sticky note.
 */
miro.board.ui.on('drop', async ({x, y, target}) => {
  await miro.board.createStickyNote({
    x,
    y,
    content: target.innerText,
  });
});

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My panel with draggable items</title>
    <!-- Loads the Miro Web SDK -->
    <script src="https://miro.com/app/static/sdk/v2/miro.js"></script>
    <!-- Loads the companion JS file with the logic -->
    <script src="app.js"></script>
  </head>
  <body>
    <!-- The 'miro-draggable' class makes HTML items draggable -->

    <!-- The `data-drag-preview` attribute changes preview image during dragging of element -->
    <div class="miro-draggable" data-drag-preview="https://amazing-images.com/categories/cats/cute-fluffy-kitten.png">
      Kitten
    </div>

    <!-- The `data-drag-preview-width` attribute changes preview image width. The `data-drag-preview-height` will work in the same way -->
    <div
      class="miro-draggable"
      data-drag-preview-width="100"
      data-drag-preview="https://amazing-images.com/categories/dogs/beautiful-dog.jpg"
    >
      Dog
    </div>

    <!-- The `data-drag-preview-width` + `data-drag-preview-height` force apply size and ignore aspect ratios of image -->
    <div
      class="miro-draggable"
      data-drag-preview-width="100"
      data-drag-preview-height="100"
      data-drag-preview="https://amazing-images.com/categories/dragons/scary-dragon.svg"
    >
      Dragon
    </div>
  </body>
</html>

on(event: 'icon:click', handler: () => void) => void

/** When a user clicks the icon:
 *  1. The openPanel method is called
 *  2. The method opens the HTML page: `panel.html`
 */
miro.board.ui.on('icon:click', async () => {
  await miro.board.ui.openPanel({
    url: 'panel.html',
  });
});

on(event: 'app_card:open', handler: (event: AppCardOpenEvent) => void): void;

/** When a user clicks the icon that expands an app card to view it in detail:
 *  1. The 'openModal' method is called
 *  2. The method opens a modal to display the specific app card content fetched from the URL
 */
// Listen to the 'app_card:open' event
miro.board.ui.on('app_card:open', (event) => {
  console.log('Subscribed to app card open event', event);
  const {appCard} = event;

  // Build a URL containing the app card ID.
  // You pass this URL with the 'openModal()' method below.
  // The code in the modal uses the 'appCardId' URL query parameter
  // to identify which app card was opened.
  const url = `https://my.app.example.com/modal.html?appCardId=${appCard.id}`;

  // Open the modal to display the content of the fetched app card
  miro.board.ui.openModal({
    url,
  });
});

on(event: 'app_card:connect', handler: (event: AppCardConnectEvent) => void): void;

/** In a typical flow:
 *  1. The app creates an app card.
 *     The 'disconnected' status icon is not clickable, yet.
 *  2. The app listens to the 'app_card:connect' event.
 *     The 'disconnected' status icon is clickable.
 *  3. The app listens to the 'app_card:open' event.
 *  4. When users click the 'disconnected' status icon, a tooltip prompts them to connect the app card to its data source.
 *  5. When the app card is connected, its status icon changes to 'connected'.
 *  6. Now the app can open a modal to display the app card detail view.
 */

// Create an app card
const appCard = await miro.board.createAppCard({
  title: 'This is the title of the app card',
  // Default status of new app cards
  status: 'disconnected',
});

// Listen to the 'app_card:connect' event
miro.board.ui.on('app_card:connect', (event) => {
  console.log('Connect the app card to its data source');
  const appcard = event.appCard;
  // Update the app card status to 'connected'
  appcard.status = 'connected';
  // Propagate the app card updates to the board
  appcard.sync();
});

// Listen to the 'app_card:open' event
miro.board.ui.on('app_card:open', (event) => {
  console.log('Subscribed to app card open event', event);
  // URL containing the app card ID.
  // The content is displayed inside the modal
  const url = `https://my.app.example.com/modal.html?appCardId=${appCard.id}`;
  // Open the modal to display the content of the fetched app card
  miro.board.ui.openModal({
    url,
  });
});

on(event: 'selection:update', handler: (event: SelectionUpdateEvent) => void): void;

/** When a user clicks and selects multiple board items on a board:
 *  1. The 'selection:update' method logs the selection to the developer console
 *  2. A filter identifies sticky note items in the selection
 *  3. The color of the sticky notes is changed to 'cyan'
 */

// Listen to the 'selection:update' event
miro.board.ui.on('selection:update', async (event) => {
  console.log('Subscribed to selection update event', event);
  console.log(event.items);
  const selectedItems = event.items;

  // Filter sticky notes from the selected items
  const stickyNotes = selectedItems.filter((item) => item.type === 'sticky_note');

  // Change the fill color of the sticky notes
  for (const stickyNote of stickyNotes) {
    stickyNote.style.fillColor = 'cyan';
    await stickyNote.sync();
  }
});

on(event: 'online_users:update', handler: (event: OnlineUsersUpdateEvent) => void): void

/** When the number of online users changes, identify the
 *  new online users and greet them with a notification.
 */

let currentOnlineUsers = [];
// Listen to the 'online_users:update' event.
await miro.board.ui.on('online_users:update', async (event) => {
  console.log('Subscribed to the update of online users');
  console.log('Online users: ', event.users);
  const onlineUsers = event.users;

  // Identify the new online users.
  const newUsers = onlineUsers.filter((user) => !currentOnlineUsers.find((u) => u.id === user.id));
  console.log('New users:', newUsers);

  // Greet the new online users.
  for (const newUser of newUsers) {
    await miro.board.notifications.showInfo(`Hello, ${newUser.name}!`);
  }

  currentOnlineUsers = onlineUsers;
});

on(event: 'items:create', handler: (event: ItemsCreateEvent) => void): void;

/** When a user creates a new item on a board:
 *  1. 'items:create' logs the created items to the developer console.
 *  2. In the group of created items, a filter identifies sticky notes.
 *  3. The color of the sticky notes is set to 'cyan'.
 */

// Listen to the 'items:create' event.
miro.board.ui.on('items:create', async (event) => {
  console.log('Subscribed to the creation of new board items', event);
  console.log(event.items);
  const createdItems = event.items;

  // Filter sticky notes from the created items.
  const stickyNotes = createdItems.filter((item) => item.type === 'sticky_note');

  // Change the fill color of the sticky notes.
  for (const stickyNote of stickyNotes) {
    stickyNote.style.fillColor = 'cyan';
    await stickyNote.sync();
  }
});

on(event: 'experimental:items:update', handler: (event: ItemsUpdateEvent) => void): void;

/**
 * When a user updates one or more items on the board:
 * 'experimental:items:update' logs all the updated board items to the developer console.
 */

// Listen to the 'experimental:items:update' event.
miro.board.ui.on('experimental:items:update', async (event) => {
  console.log('Subscribed to updates of board items', event);
  console.log('Updated items: ', event.items);
});

on(event: 'items:delete', handler: (event: ItemsDeleteEvent) => void): void;

/**
 * When a user deletes one or more items from the board:
 * 'items:delete' logs all deleted board items to the developer console.
 */

// Listen to the 'items:delete' event.
miro.board.ui.on('items:delete', async (event) => {
  console.log('Subscribed the deletion of board items', event);
  console.log('Deleted items: ', event.items);
});

on(event: `custom:${string}`, handler: (event: CustomEvent) => void): void;

miro.board.ui.off(event, handler);

off(event: 'drop', handler: (event: DropEvent) => void): void

// Add a 'drop' event handler to drag and drop images.
const drop = async (event: DropEvent) => {
  const {x, y, target} = event;
  if (target instanceof HTMLImageElement) {
    const image = await miro.board.createImage({
      x,
      y,
      url: target.src,
    });
  }
};

// Register the 'drop' event so that the app listens to it.
miro.board.ui.on('drop', drop);

// Unsubscribe from the 'drop' handler.
// The app no longer creates image items on drag and drop.
miro.board.ui.off('drop', drop);

off(event: 'icon:click', handler: () => void) => void

// Add an 'iconClick' event handler to open a panel upon clicking an icon.
const iconClick = async () => {
  await miro.board.ui.openPanel({
    url: 'panel.html',
  });
};

// Register the 'icon:click' event so that the app listens to it.
miro.board.ui.on('icon:click', iconClick);

// Unsubscribe from the 'icon:click' event handler.
// The app no longer enables opening a panel when clicking an icon.
miro.board.ui.off('icon:click', iconClick);

off(event: 'app_card:open', handler: (event: AppCardOpenEvent) => void): void;

// Create an app card.
const appCard = await miro.board.createAppCard({
  title: 'This is the title of the app card',
  status: 'disconnected',
});

// Add an 'appCardOpen' event handler for the 'app_card:open' event.
const appCardOpen = async (event: AppCardOpenEvent) => {
  const appcard = event.appCard;
  const url = `https://my.app.example.com/modal.html?appCardId=${appCard.id}`;
  miro.board.ui.openModal({
    url,
  });
};

// Register the 'app_card:open' event so that the app listens to it.
miro.board.ui.on('app_card:open', appCardOpen);

// Unsubscribe from the 'app_card:open' event handler.
// The app no longer enables opening a modal with the detail view of an app card.
miro.board.ui.off('app_card:open', appCardOpen);

off(event: 'app_card:connect', handler: (event: AppCardConnectEvent) => void): void;

// Create an app card.
const appCard = await miro.board.createAppCard({
  title: 'This is the title of the app card',
  status: 'disconnected',
});

// Add an 'appCardConnect' event handler for the 'app_card:connect' event.
const appCardConnect = async (event: AppCardConnectEvent) => {
  const appcard = event.appCard;
  appcard.status = 'connected';
  appcard.sync();
};

// Register the 'app_card:connect' event so that the app listens to it.
miro.board.ui.on('app_card:connect', appCardConnect);

// Unsubscribe from the 'app_card:connect' event handler.
// The app no longer enables connecting an app card to a data source.
miro.board.ui.off('app_card:connect', appCardConnect);

off(event: 'selection:update', handler: (event: SelectionUpdateEvent) => void): void;

// Add a 'selectionUpdate' event handler to update the color of sticky notes included in a selection.
const selectionUpdate = async (event: SelectionUpdateEvent) => {
  const selectedItems = event.items;
  const stickyNotes = selectedItems.filter((item) => item.type === 'sticky_note');
  for (const stickyNote of stickyNotes) {
    stickyNote.style.fillColor = 'cyan';
    await stickyNote.sync();
  }
};

// Register the 'selection:update' event so that the app listens to it.
miro.board.ui.on('selection:update', selectionUpdate);

// Unsubscribe from the 'selection:update' event handler.
// The app no longer enables updating the color of the sticky notes included in a selection to cyan.
miro.board.ui.off('selection:update', selectionUpdate);

off(event: 'online_users:update', handler: (event: OnlineUsersUpdateEvent) => void): void

// Add an 'online_users:update' event handler to greet new online users joining the board.
let currentOnlineUsers = [];
const onlineUsersUpdate = async (event) => {
  const onlineUsers = event.users;
  const newUsers = onlineUsers.filter((user) => !currentOnlineUsers.find((u) => u.id === user.id));

  for (const newUser of newUsers) {
    await miro.board.notifications.showInfo(`Hello, ${newUser.name}!`);
  }

  currentOnlineUsers = onlineUsers;
};

// Register the 'online_users:update' event so that the app listens to it.
await miro.board.ui.on('online_users:update', onlineUsersUpdate);

// Unsubscribe from the 'online_users:update' event handler.
// The app no longer greets new online users.
await miro.board.ui.off('online_users:update', onlineUsersUpdate);

off(event: 'items:create', handler: (event: ItemsCreateEvent) => void): void;

// Add an 'itemsCreate' event handler to update the color of user-created sticky notes.
const itemsCreate = async (event: ItemsCreateEvent) => {
  const createdItems = event.items;
  const stickyNotes = createdItems.filter((item) => item.type === 'sticky_note');
  for (const stickyNote of stickyNotes) {
    stickyNote.style.fillColor = 'cyan';
    await stickyNote.sync();
  }
};

// Register the 'items:create' event so that the app listens to it.
miro.board.ui.on('items:create', itemsCreate);

// Unsubscribe from the 'items:create' event handler.
// The app no longer updates the color of user-created sticky notes.
miro.board.ui.off('items:create', itemsCreate);

off(event: 'experimental:items:update', handler: (event: ItemsUpdateEvent) => void): void;

// Add an 'itemsUpdate' event handler to log user-updated board items to the developer console.
const itemsUpdate = async (event: ItemsUpdateEvent) => {
  console.log(event.items);
};

// Register the 'experimental:items:update' event so that the app listens to it.
miro.board.ui.on('experimental:items:update', itemsUpdate);

// Unsubscribe from the 'experimental:items:update' event handler.
// The app no longer enables logging user-updated board items.
miro.board.ui.off('experimental:items:update', itemsUpdate);

off(event: 'items:delete', handler: (event: ItemsDeleteEvent) => void): void;

// Add an 'itemsDelete' event handler to log user-deleted board items to the developer console.
const itemsDelete = async (event: ItemsDeleteEvent) => {
  console.log(event.items);
};

// Register the 'items:delete' event so that the app listens to it.
miro.board.ui.on('items:delete', itemsDelete);

// Unsubscribe from the 'items:delete' event handler.
// The app no longer enables logging user-deleted board items.
miro.board.ui.off('items:delete', itemsDelete);

off(event: `custom:${string}`, handler: (event: CustomEvent) => void): void;