Frame
Frame.Frame
Frame
Experimental
Frames are parent items that can group and hold together other items on a board, such as shapes, text, images, and so on.
When an item is a child of a parent frame, the child positioning reference is relative to the parent frame.
Frames help structure and organize board content:
- They enable exporting board content to PDF, or to save it as a presentation.
- They are indexed; they make it easier to search for and find board content.
- When presentation mode is enabled on a board, indexed frames define the sequence of the slides in the presentation.
When creating or updating a frame item, you can define its dimensions in the following way:
- Set or update only
width
.
Default width:100
dp - Set or update only
height
.
Default height:100
dp - Set or update
width
andheight
at the same time.
ℹ️ Note:
- If you resize a parent frame containing child items, the Web SDK throws an error if one or more children fall outside the parent frame after resizing it.
This isn't allowed, because it would break the parent/child relationship between the items.
To break the relationship, explicitly remove the child item(s) from the parent frame.
Example:
const frame = await miro.board.createFrame({
title: 'This frame ratio is 16:9',
style: {
fillColor: '#ffffff',
},
x: 0, // Default value: horizontal center of the board
y: 0, // Default value: vertical center of the board
width: 800,
height: 450,
});
// Output the created item to the developer console
console.log(frame);
Frame item:
Figure 1. A frame parent item containing a sticky note as a child item.
Table of contents
Properties
- type
- x
- y
- width
- height
- title
- childrenIds
- style
- id
- origin
- parentId
- createdAt
- createdBy
- modifiedAt
- modifiedBy
Methods
Properties
type
• Readonly
type: "frame"
Defines the type of item.
Item type is useful to retrieve specific items from a board.
For example, you can fetch all card and shape items from the board, and then carry out an action on them.
Example:
// Get all items from the board
const items = await miro.board.get();
// Count all card and shape items on the board
let cards = 0;
let shapes = 0;
items.forEach((items) => {
switch (items.type) {
case 'card':
cards++;
case 'shape':
shapes++;
}
});
// Output to the console the total amount of card and shape items
console.log('The current board has ${cards} cards and ${shapes} shapes.');
Overrides
x
• x: number
The x-axis coordinate of an item is the horizontal distance in dp of the center point of the item from the center point of the board.
The center point of the board has x: 0
and y: 0
coordinates.
Default: 0
See also:
Overrides
y
• y: number
The y-axis coordinate of an item is the vertical distance in dp of the center point of the item from the center point of the board.
The center point of the board has x: 0
and y: 0
coordinates.
Default: 0
See also:
Overrides
width
• Readonly
width: number
Width of the item in dp.
See also:
height
• Readonly
height: number
Height of the item in dp.
See also:
title
• title: string
= ''
A short text header for the frame.
The text must be shorter than 6000 characters.
title
supports only plain text.
childrenIds
• childrenIds: string
[]
An array of unique identifiers.
The IDs represent child items inside the frame.
They help retrieve child items inside a parent item.
style
• style: Object
The style
object groups properties that define the layout, the look and feel of specific elements of an item, when it's displayed on the board.
For example: background color, font family, font type, horizontal and vertical alignment of the text, text color, and so on.
The Miro Web SDK doesn't support all standard style, yet. Additional styles will be included in future releases.
style
data structure:
style: {
fillColor: 'transparent', // Default value: transparent (no fill color)
},
Hex value representing the background color that fills the area of the frame.
Default: transparent
(no fill color)
Type declaration
Name | Type |
---|---|
fillColor | string |
id
• Readonly
id: string
origin
• origin: "center"
origin
marks:
- The positioning reference point of a board item.
This is the point used to calculate thex
andy
coordinates of an item when it's positioned on the board, or when it's a child inside a parent item. - The rotation pivot point of a board item that supports rotation.
origin
accepts only one value: center
.
Any other value throws an error.
parentId
• Readonly
parentId: null
| string
If an item is a child of another item, the child's parentId
returns the unique identifier of the corresponding parent item.
If an item has no parent, its parentId
is null
.
You can use the value to retrieve a tree structure when items are nested inside containers.
For example, sticky notes inside frames.
createdAt
• Readonly
createdAt: string
Timestamp
Date and time when the item was created.
Format: UTC, ISO 8601.
Includes a trailing Z offset.
Example: 2021-05-18T07:59:01Z
createdBy
• Readonly
createdBy: string
Miro users are automatically assigned a unique ID.
createdBy
contains the ID of the user who created the item.
Example: 3658432978520043388
modifiedAt
• Readonly
modifiedAt: string
Timestamp
Date and time when the item was last modified.
Format: UTC, ISO 8601.
Includes a trailing Z offset.
Example: 2021-05-18T07:59:01Z
modifiedBy
• Readonly
modifiedBy: string
Miro users are automatically assigned a unique ID.
modifiedBy
contains the ID of the user who applied the most recent edit to the item.
Example: 3658432978520043388
Methods
add
▸ add<T
>(item
): Promise
<T
>
Adds an item to a frame as a child.
The frame becomes the corresponding parent.
The add()
method takes a board item as an argument.
The item must exist on the board, before you can add it to a frame using add()
.
add()
establishes a parent/child relationship between the containing frame and the items inside it.
After calling add()
:
- The
parentId
of the child item corresponds to the parent frame ID. - The child item ID is added to the frame
childrenIds
array.
This enables repositioning a frame on the board along with its children, as they keep the same relative position inside the parent frame.
It also affects the positioning reference of the child item, because its x
and y
values are no longer relative to the center of the board.
After adding an item to a frame, the x
and y
coordinates of the child item inside the parent frame mark the center point of the child, relative to the top-left corner of the parent frame.
The promise that the method returns can fail if:
- The parent frame doesn't exist.
- The child item is located outside the bounds of the parent frame.
- The child item is already a child inside a different frame.
Type parameters
Name | Type |
---|---|
T | extends BaseItem <T > |
Parameters
Name | Type |
---|---|
item | T |
Returns
Promise
<T
>
remove
▸ remove<T
>(item
): Promise
<void
>
Removes a child item from a frame.
The method removes the parent-child relationship between the items.
Both items still exist on the board as independent, detached items.
This affects the positioning reference of the item, because its x
and y
values are no longer relative to the top-left corner of the frame.
After removing an item from a frame, the item's x
and y
coordinates mark the center point of the item, relative to the center of the board.
The frame.remove()
method takes an item as an argument.
The promise that the method returns can fail if:
- The child item you're trying to remove doesn't exist.
- The item you're trying to remove isn't a child of the frame.
- The frame doesn't exist.
Example:
// Create a frame
const frame = await miro.board.createFrame({
title: 'this frame ratio is 16:9',
width: 800,
height: 450,
});
// Create a text item
const text = await miro.board.createText({
content: 'this is a piece of text',
style: {
fillColor: '#fff9b1', // Light yellow
},
});
// Add the text item as a child of the parent frame
await frame.add(text);
// Move the frame on the board.
// The child text item moves along with the frame:
// its coordinates are relative to the top-left corner of the frame
frame.x = -400;
frame.y = -500;
await frame.sync();
// Remove the child text item from the parent frame
await frame.remove(text);
// Move the frame on the board.
// The text item doesn't move along with the frame:
// its coordinates are relative to the center of the board
frame.x = 400;
frame.y = 500;
await frame.sync();
// Remove the text item from the board
await miro.board.remove(text);
// Remove the frame from the board
await miro.board.remove(frame);
Type parameters
Name | Type |
---|---|
T | extends BaseItem <T > |
Parameters
Name | Type |
---|---|
item | T |
Returns
Promise
<void
>
getChildren
▸ getChildren(): Promise
<Item
[]>
Returns an array containing all the child items inside a parent frame.
If a frame has no children, the method returns an empty array.
Example:
// Specify all frame items on the board
let frames = await miro.board.get({type: 'frame'});
// Log to the console the child items of the frames
for (const frame of frames) {
const children = await frame.getChildren();
console.log(children);
}
Returns
Promise
<Item
[]>
sync
▸ sync(): Promise
<void
>
sync
propagates to the board any changes to item and tag properties.
After updating the properties of an item or a tag, sync it with the board to:
- Propagate to the board the changes applied to the item or to the tag.
- Make the changes visible on the board.
All board items and tags require sync
to make any changes to their properties visible on the board.
For more information and examples, see Update and sync item properties.
Returns
Promise
<void
>
Updated 6 days ago