ThumbnailList

API reference for the "ThumbnailList" control.

Renders a list of thumbnails within the Canva UI.

To learn how controls work, refer to Rich controls.

Usage

canva.create('thumbnail_list', {
id: 'thumbnailListExample',
selectedThumbnailId: 'beach',
items: [
{
thumbnailId: 'beach',
label: 'Beach',
src: 'https://picsum.photos/id/100/256/256',
},
{
thumbnailId: 'bird',
label: 'Bird',
src: 'https://picsum.photos/id/50/256/256',
},
{
thumbnailId: 'trees',
label: 'Trees',
src: 'https://picsum.photos/id/10/256/256',
},
],
});

Parameters

Name

Type

Required

Description

controlType

string

Yes

The type of control. To create a thumbnail list, the value must be "thumbnail_list".

opts

object

Yes

Properties for configuring the control.

opts.id

string

Yes

A unique ID for the control.

opts.items

Array<Item>

Yes

The thumbnails to display in the list of thumbnails.

opts.disabled

boolean

No

If true, the user can't interact with the control.

opts.selectedThumbnailId

string

No

The ID of the selected thumbnail.

Event

Name

Type

Required

Description

opts

object

Yes

Information about the event.

opts.message

object

Yes

Information about the event.

opts.message.commit

boolean

Yes

The value of this property is always true.

opts.message.controlId

string

Yes

The id of the control.

opts.message.controlType

string

Yes

The type of control. The value of this property is always "thumbnail_list".

opts.message.message

object

Yes

Additional information about the event.

opts.message.message.type

string

Yes

The type of event. The value of this property is always "selected".

opts.message.message.thumbnailId

string

Yes

The ID of the selected thumbnail.

Types

Item

Represents an individual thumbnail in a list of thumbnails.

Properties

Name

Type

Required

Description

thumbnailId

string

Yes

A unique ID for the thumbnail.

label

string

Yes

A human readable label that appears beneath the thumbnail.

src

string

Yes

The URL or Data URI of an image.

Example

const canva = window.canva.init();
const state = {
thumbnailListExample: 'beach',
};
canva.onReady(() => {
renderControls();
});
canva.onControlsEvent(async (opts) => {
if (opts.message.commit) {
return;
}
if (opts.message.controlType === 'thumbnail_list') {
state[opts.message.controlId] = opts.message.message.thumbnailId;
}
renderControls();
});
function renderControls() {
const controls = [
canva.create('thumbnail_list', {
id: 'thumbnailListExample',
selectedThumbnailId: state.thumbnailListExample,
items: [
{
thumbnailId: 'beach',
label: 'Beach',
src: 'https://picsum.photos/id/100/256/256',
},
{
thumbnailId: 'bird',
label: 'Bird',
src: 'https://picsum.photos/id/50/256/256',
},
{
thumbnailId: 'trees',
label: 'Trees',
src: 'https://picsum.photos/id/10/256/256',
},
],
}),
];
canva.updateControlPanel(controls);
}