docs/api/canvas.md
You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object
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(...);
canvas:dragenter Something is dragged inside the canvas. DataTransfer instance and dragged content are passed as arguments.
canvas:dragover Something is dragging on the canvas. Triggering event is passed as an argument.
canvas:dragend When a drag operation is ended, triggering event is 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:update Canvas was updated.
canvas:tools:update Canvas tools were updated.
canvas:move:start Canvas move started.
canvas:move Canvas is moving.
canvas:move:end Canvas move ended.
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);
});
canvas:frame:unload Frame is unloading from the canvas.editor.on('canvas:frame:unload', ({ frame }) => {
console.log('Unloading frame', frame);
});
Get configuration object
Returns Object
Get the canvas element
Returns HTMLElement
Get the main frame element of the canvas
Returns HTMLIFrameElement
Get the main frame window instance
Returns Window
Get the main frame document element
Returns HTMLDocument
Get the main frame body element
Returns HTMLBodyElement
Set custom badge naming strategy
f Function canvas.setCustomBadgeLabel(function(component){
return component.getName();
});
Get canvas rectangular data
Returns Object
Start custom drag-and-drop process.
dragSource DragSource<Component> The source object for the drag operation, containing the component being dragged.// as component definition
canvas.startDrag({
content: { type: 'my-component' }
});
// as HTML
canvas.startDrag({
content: '<div>...</div>'
});
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.
canvas.startDrag({...});
// ... drag finished ...
canvas.endDrag();
Check if the canvas is focused
Returns Boolean
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' }.
el (HTMLElement | Component)
opts Object Options, same as options for scrollIntoView (optional, default {})
opts.force Boolean Force the scroll, even if the element is already visible (optional, default false)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 });
Set canvas zoom value
value Number The zoom value, from 0 to 100opts SetZoomOptions (optional, default {})canvas.setZoom(50); // set zoom to 50%
Returns this
Get canvas zoom value
canvas.setZoom(50); // set zoom to 50%
const zoom = canvas.getZoom(); // 50
Returns Number
Set canvas position coordinates
canvas.setCoords(100, 100);
Returns this
Get canvas position coordinates
canvas.setCoords(100, 100);
const coords = canvas.getCoords();
// { x: 100, y: 100 }
Returns Object Object containing coordinates
Get the last created Component from a drag & drop to the canvas.
Returns (Component | undefined)
Add or update canvas spot.
props Object Canvas spot properties.opts AddOptions (optional, default {})// 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
Get canvas spots.
spotProps Object? Canvas spot properties for filtering the result. With no properties, all available spots will be returned. (optional, default {})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<CanvasSpot>
Remove canvas spots.
spotProps (Object | Array<CanvasSpot>)? Canvas spot properties for filtering spots to remove or an array of spots to remove. With no properties, all available spots will be removed. (optional, default {})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<CanvasSpot>
Check if the built-in canvas spot has a declared custom rendering.
type String Built-in canvas spot typegrapesjs.init({
// ...
canvas: {
// avoid rendering the built-in 'target' canvas spot
customSpots: { target: true }
}
});
// ...
canvas.hasCustomSpot('select'); // false
canvas.hasCustomSpot('target'); // true
Returns Boolean
Transform a box rect from the world coordinate system to the screen one.
boxRect Object Returns Object
Update canvas for spots/tools positioning.