GrapesJS

# Canvas

You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object (opens new window)

const editor = grapesjs.init({
 canvas: {
   // options
 }
})

Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.

// Listen to events
editor.on('canvas:drop', () => { ... });

// Use the API
const canvas = editor.Canvas;
canvas.setCoords(...);

# Available Events

  • canvas:dragenter Something is dragged inside the canvas, DataTransfer instance passed as an argument.

  • canvas:dragover Something is dragging on the canvas, DataTransfer instance passed as an argument.

  • canvas:dragend When a drag operation is ended, DataTransfer instance passed as an argument.

  • canvas:dragdata On any dataTransfer parse, DataTransfer instance and the result are passed as arguments. By changing result.content you're able to customize what is dropped.

  • canvas:drop Something is dropped in canvas, DataTransfer instance and the dropped model are passed as arguments.

  • canvas:spot Spots updated.

editor.on('canvas:spot', () => {
 console.log('Spots', editor.Canvas.getSpots());
});
  • canvas:spot:add New canvas spot added.
editor.on('canvas:spot:add', ({ spot }) => {
 console.log('Spot added', spot);
});
  • canvas:spot:update Canvas spot updated.
editor.on('canvas:spot:update', ({ spot }) => {
 console.log('Spot updated', spot);
});
  • canvas:spot:remove Canvas spot removed.
editor.on('canvas:spot:remove', ({ spot }) => {
 console.log('Spot removed', spot);
});
  • canvas:coords Canvas coordinates updated.
editor.on('canvas:coords', () => {
 console.log('Canvas coordinates updated:', editor.Canvas.getCoords());
});
  • canvas:zoom Canvas zoom updated.
editor.on('canvas:zoom', () => {
 console.log('Canvas zoom updated:', editor.Canvas.getZoom());
});
  • canvas:pointer Canvas pointer updated.
editor.on('canvas:pointer', () => {
 console.log('Canvas pointer updated:', editor.Canvas.getPointer());
});
  • canvas:refresh Canvas was refreshed to update elements on top, like spots/tools (eg. via editor.Canvas.refresh() or on frame resize).
editor.on('canvas:refresh', (canvasRefreshOptions) => {
 console.log('Canvas refreshed with options:', canvasRefreshOptions);
});
  • canvas:frame:load Frame loaded in canvas. The event is triggered right after iframe's onload.
editor.on('canvas:frame:load', ({ window }) => {
 console.log('Frame loaded', window);
});
  • canvas:frame:load:head Frame head loaded in canvas. The event is triggered right after iframe's finished to load the head elements (eg. scripts)
editor.on('canvas:frame:load:head', ({ window }) => {
 console.log('Frame head loaded', window);
});
  • canvas:frame:load:body Frame body loaded in canvas. The event is triggered when the body is rendered with components.
editor.on('canvas:frame:load:body', ({ window }) => {
 console.log('Frame completed the body render', window);
});

# getConfig

Get configuration object

Returns Object (opens new window)

# getElement

Get the canvas element

Returns HTMLElement (opens new window)

# getFrameEl

Get the main frame element of the canvas

Returns HTMLIFrameElement (opens new window)

# getWindow

Get the main frame window instance

Returns Window (opens new window)

# getDocument

Get the main frame document element

Returns HTMLDocument

# getBody

Get the main frame body element

Returns HTMLBodyElement (opens new window)

# setCustomBadgeLabel

Set custom badge naming strategy

# Parameters

# Examples

canvas.setCustomBadgeLabel(function(component){
 return component.getName();
});

# getRect

Get canvas rectangular data

Returns Object (opens new window)

# startDrag

Start custom drag-and-drop process.

# Parameters

  • dragSource DragSource<Component> The source object for the drag operation, containing the component being dragged.

# Examples

// as component definition
canvas.startDrag({
 content: { type: 'my-component' }
});
// as HTML
canvas.startDrag({
 content: '<div>...</div>'
});

# endDrag

Ends the drag-and-drop process, resetting the drag source and clearing any drag results. This method can be used to finalize custom drag-and-drop content operations.

# Examples

canvas.startDrag({...});
// ... drag finished ...
canvas.endDrag();

# hasFocus

Check if the canvas is focused

Returns Boolean (opens new window)

# scrollTo

Scroll canvas to the element if it's not visible. The scrolling is executed via scrollIntoView API and options of this method are passed to it. For instance, you can scroll smoothly by using { behavior: 'smooth' }.

# Parameters

# Examples

const selected = editor.getSelected();
// Scroll smoothly (this behavior can be polyfilled)
canvas.scrollTo(selected, { behavior: 'smooth' });
// Force the scroll, even if the element is already visible
canvas.scrollTo(selected, { force: true });

# setZoom

Set canvas zoom value

# Parameters

# Examples

canvas.setZoom(50); // set zoom to 50%

Returns this

# getZoom

Get canvas zoom value

# Examples

canvas.setZoom(50); // set zoom to 50%
const zoom = canvas.getZoom(); // 50

Returns Number (opens new window)

# setCoords

Set canvas position coordinates

# Parameters

# Examples

canvas.setCoords(100, 100);

Returns this

# getCoords

Get canvas position coordinates

# Examples

canvas.setCoords(100, 100);
const coords = canvas.getCoords();
// { x: 100, y: 100 }

Returns Object (opens new window) Object containing coordinates

# getLastDragResult

Get the last created Component from a drag & drop to the canvas.

Returns (Component | undefined (opens new window))

# addSpot

Add or update canvas spot.

# Parameters

# Examples

// Add new canvas spot
const spot = canvas.addSpot({
 type: 'select', // 'select' is one of the built-in spots
 component: editor.getSelected(),
});

// Add custom canvas spot
const spot = canvas.addSpot({
 type: 'my-custom-spot',
 component: editor.getSelected(),
});
// Update the same spot by reusing its ID
canvas.addSpot({
 id: spot.id,
 component: anotherComponent,
});

Returns CanvasSpot

# getSpots

Get canvas spots.

# Parameters

  • spotProps Object (opens new window)? Canvas spot properties for filtering the result. With no properties, all available spots will be returned. (optional, default {})

# Examples

canvas.addSpot({ type: 'select', component: cmp1 });
canvas.addSpot({ type: 'select', component: cmp2 });
canvas.addSpot({ type: 'target', component: cmp3 });

// Get all spots
const allSpots = canvas.getSpots();
allSpots.length; // 3

// Get all 'select' spots
const allSelectSpots = canvas.getSpots({ type: 'select' });
allSelectSpots.length; // 2

Returns Array (opens new window)<CanvasSpot>

# removeSpots

Remove canvas spots.

# Parameters

# Examples

canvas.addSpot({ type: 'select', component: cmp1 });
canvas.addSpot({ type: 'select', component: cmp2 });
canvas.addSpot({ type: 'target', component: cmp3 });

// Remove all 'select' spots
canvas.removeSpots({ type: 'select' });

// Remove spots by an array of canvas spots
const filteredSpots = canvas.getSpots().filter(spot => myCustomCondition);
canvas.removeSpots(filteredSpots);

// Remove all spots
canvas.removeSpots();

Returns Array (opens new window)<CanvasSpot>

# hasCustomSpot

Check if the built-in canvas spot has a declared custom rendering.

# Parameters

# Examples

grapesjs.init({
 // ...
 canvas: {
   // avoid rendering the built-in 'target' canvas spot
   customSpots: { target: true }
 }
});
// ...
canvas.hasCustomSpot('select'); // false
canvas.hasCustomSpot('target'); // true

Returns Boolean (opens new window)

# getWorldRectToScreen

Transform a box rect from the world coordinate system to the screen one.

# Parameters

Returns Object (opens new window)

# refresh

Update canvas for spots/tools positioning.

# Parameters

← ‍ ‍ ‍ Frame →