GrapesJS

# Canvas

WIP

The documentation of this module is still a work in progress.

WARNING

This guide applies to GrapesJS v0.21.5 or higher.

# Configuration

To change the default configuration, pass the canvas property in the main configuration object.

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

Check the full list of available options here: Canvas Config (opens new window)

# Canvas Spots

Canvas spots are elements drawn on top of the canvas. They can represent anything you need, but their most common use is to display information about components in the canvas and provide controls for managing them.

To better understand canvas spots, let's see how their built-in types are used.

# Built-in spot types

# Select type

The select type is responsible for showing selected components and rendering the available toolbar items for the last selected component.

TIP

Get the toolbar items from the component.

const toolbarItems = editor.getSelected().toolbar;

# Resize type

The resize type allows resizing of a component, based on the component's resizable options.

TIP

Get the component resizable options.

const resizable = editor.getSelected().resizable;

# Target type

The target type highlights a component during operations such as drag and drop to show where the dragged component will be placed.

WARNING

The default green position indicator is not part of the spot, but you can easily customize it via CSS.

.gjs-placeholder.horizontal {
  border-color: transparent red;
}
.gjs-placeholder.vertical {
  border-color: red transparent;
}
.gjs-placeholder-int {
  background-color: red;
}

# Hover type

The hover type is used to highlight the hovered component and show the component name.

TIP

Get the component name.

const name = editor.getSelected().getName();

# Spacing type

The spacing type is used to show component offsets such as padding and margins (visible on the hover type image above).

# Disable built-in types

You can disable the rendering of built-in canvas spots (some or all of them) during the editor initialization.

grapesjs.init({
  // ...
  canvas: {
    // Disable only the hover type spot
    customSpots: {
      hover: true,
    },
    // Disable all built-in spots
    customSpots: true,
  },
});

In the next section, we'll see how it's possible to reuse the built-in spots and create your own.

# Spots customization

In the example below, we'll reuse the built-in hover canvas spot to render a custom highlighting rectangle, disabling the default one. We'll also create a new spot to render a button below the selected text component.

DEMO (opens new window)

A few points to keep in mind:

  • Our custom container has to be moved inside the GrapesJS spots container.
editor.onReady(() => {
  Canvas.getSpotsEl().appendChild(this.$el);
});
  • We pass the component to our custom spot so its style coordinates are updated correctly when we scroll the page or update the component.
Canvas.addSpot({ type: customSpotType, component });
  • Each spot is positioned using spot.getStyle().
<div ... class="spot" :style="spot.getStyle()">...</div>
  • By default, the spots container uses pointer-events: none to prevent spots from blocking interaction with components. We therefore have to re-enable pointer events on the button to make it interactive.
.spot-text-btn {
  /*...*/
  pointer-events: auto;
}

# Events

For a complete list of available events, check here.