Timer

The timer namespace provides control over the built-in Miro timer feature. This is available under miro.board.timer.

start: starts the timer for a specified amount of milliseconds.
get: gets the current state of the timer.
stop: stops the timer.
pause: pauses the timer.
resume: resumes the timer.
prolong: prolongs the timer by a specified amount of milliseconds.
isStarted: checks if the timer has started or not.
on: subscribes to different timer events.
off: unsubscribes from previously subscribed timer events.

Methods

start(...)

(duration: number) => Promise<TimerInstance>

🚦 Rate limit: Level 1

Starts timer for specified amount of milliseconds.

This method returns a Promise that resolves to a TimerInstance object, representing the current state of the timer

duration holds the amount of milliseconds that used to start or prolong the timer.

It should be greater than 0

Example:

// Starts the timer for 1 minute, will return started Timer instance or throw an error.
const timer = await miro.board.timer.start(60 * 1000);

console.log(timer) // TimerInstance { restDuration: 60000, status: 'STARTED', totalDuration: 60000 }

get(...)

() => Promise<TimerInstance>

🚦 Rate limit: Level 1

Gets the current state ot the timer.

This method returns a Promise that resolves to a TimerInstance object.

Example:

// Gets the current state of timer.
const timer = await miro.board.timer.get();

console.log(timer) // TimerInstance { restDuration: 9000, status: 'STARTED', totalDuration: 60000 }

stop(...)

() => Promise<TimerInstance>

🚦 Rate limit: Level 1

Stops timer.

This method returns a Promise that resolves to a TimerInstance object, representing the current state of the timer

Example:

// Stops the timer, this async method will return instance of timer after stopping if operation was successful or throw error if not.
const isSuccessful = await miro.board.timer.stop();

pause(...)

() => Promise<TimerInstance>

🚦 Rate limit: Level 1

Pauses timer.

This method returns a Promise that resolves to a TimerInstance object, representing the current state of the timer.

Example:

// Pauses the timer, this async method will return instance of timer after pause if operation was successful or throw error if not.
const isSuccessful = await miro.board.timer.pause();

resume(...)

() => Promise<TimerInstance>

🚦 Rate limit: Level 1

Resumes timer.

This method returns a Promise that resolves to a TimerInstance object, representing the current state of the timer.

Example:

// Resumes the timer, this async method will return instance of timer after resuming if operation was successful or throw error if not.
const isSuccessful = await miro.board.timer.resume();

prolong(...)

(duration: number) => Promise<TimerInstance>

🚦 Rate limit: Level 1

Prolongs timer by provided amount of milliseconds.

This method returns a Promise that resolves to a TimerInstance object, representing the current state of the timer.

Example:

// Prolongs the timer by 1 minute, will return instance of timer after prolonging if operation was successful or throw error if not.
const timer = await miro.board.timer.prolong(60 * 1000);

isStarted(...)

() => Promise<boolean>

🚦 Rate limit: Level 1

Checks if timer is started or no.

Example:

// Checks if the timer is started or no, this async method will return boolean value.
const isTimerStarted = await miro.board.timer.isStarted();

on(...)

(event: TimerEventType, handler: (event: TimerEvent) => void) => void

Subscribes to timer events in your app:

start: Triggered when timer has started.
update: Triggered when timer has updated (prolonged, paused, resumed).
finish: Triggered when timer has finished.

All handlers of the start, update, or finish event will receive a TimerEvent object as a parameter.

Examples

Example (start event):

/** When a user starts a timer:
 *  1. 'start' logs the timer properties.
 *  2. plays some random sound.
 */

// Listen to the 'start' event.
await miro.board.timer.on("start", async (event) => {
  console.log("Subscribed to the board timer start event =>", event);
  await playRandomSound();
});

Example (update event):

/** When a user, for example, prolongs a timer:
 *  1. 'update' logs the timer properties.
 *  2. logic will show notification with rest duration of updated timer.
 */

// Listen to the 'update' event.
await miro.board.timer.on("update", async (event) => {
  console.log("Subscribed to the board timer start event =>", event);
  await miro.board.notifications.showInfo(
    `Rest duration: ${event.restDuration}`
  );
});

Example (finish event):

/** When the board timer is finished:
 *  1. 'finish' logs the timer properties.
 *  2. opens the feedback form in the modal.
 */

// Listen to the 'finish' event.
await miro.board.timer.on("finish", async (event) => {
  console.log("Subscribed to the board timer finish event =>", event);
  await miro.board.ui.openModal({ url: "/feedback-form" });
});

off(...)

(event: TimerEventType, handler: (event: TimerEvent) => void) => void

Unsubscribes from previously subscribed timer events in your app

start: Triggered when timer has started.
update: Triggered when timer has updated (prolonged, paused, resumed).
finish: Triggered when timer has finished.

Examples

Example (start event):

// Add an 'timerStart' event handler to log an started timer information.
const timerStart = async (event: TimerEvent) => {
  console.log(event);
};

// Register the 'start' event so that the app listens to it.
miro.board.timer.on('start', timerStart);

// Unsubscribe from the 'start' event handler.
// The app no longer enables logging timer information on start of it.
miro.board.timer.off('start', timerStart);

Example (update event):

// Add a 'timerUpdate' event handler to log an updated timer information.
const timerUpdate = async (event: TimerEvent) => {
  console.log(event);
};

// Register the 'update' event so that the app listens to it.
miro.board.timer.on('update', timerUpdate);

// Unsubscribe from the 'update' event handler.
// The app no longer enables logging information about the updated timer.
miro.board.timer.off('update', timerUpdate);

Example (finish event):

// Add a 'timerFinish' event handler to log information about a finished timer.
const timerFinish = async (event: TimerEvent) => {
  console.log(event);
};

// Register the 'finish' event so that the app listens to it.
miro.board.timer.on('finish', timerFinish);

// Unsubscribe from the 'finish' event handler.
// The app no longer enables logging timer information on finish of this timer.
miro.board.timer.off('finish', timerFinish);

Type definitions

TimerEvent

Property	Type
`timer`	{ restDuration: number; status: 'STARTED' \| 'STOPPED' \| 'PAUSED'; totalDuration: number }

TimerInstance

Property	Type
`restDuration`	number
`status`	'STARTED' \| 'STOPPED' \| 'PAUSED'
`totalDuration`	number

All properties

Property	Type
`get(...)`	() => Promise<TimerInstance>
`isStarted(...)`	() => Promise<boolean>
`off(...)`	(event: TimerEventType, handler: (event: TimerEvent) => void) => void
`on(...)`	(event: TimerEventType, handler: (event: TimerEvent) => void) => void
`pause(...)`	() => Promise<TimerInstance>
`prolong(...)`	(duration: number) => Promise<TimerInstance>
`resume(...)`	() => Promise<TimerInstance>
`start(...)`	(duration: number) => Promise<TimerInstance>
`stop(...)`	() => Promise<TimerInstance>