GrapesJS

# Plugins

Creating plugins in GrapesJS is straightforward, and this guide will show you how.

WARNING

This guide applies to GrapesJS v0.21.2 or higher.

TIP

Looking for plugins that are tested, verified, and built to scale? Browse them all in the Grapes Studio SDK! (opens new window)

# Basic plugin

Plugins are simple functions that are run when the editor is initialized.

function myPlugin(editor) {
  // Use the API: https://grapesjs.com/docs/api/
  editor.Blocks.add('my-first-block', {
    label: 'Simple block',
    content: '<div class="my-block">This is a simple block</div>',
  });
}

const editor = grapesjs.init({
  container: '#gjs',
  plugins: [myPlugin],
});

This means plugins can be moved to separate folders to keep things organized or imported from npm.

import myPlugin from './plugins/myPlugin';
import npmPackage from '@npm/package';

const editor = grapesjs.init({
  container: '#gjs',
  plugins: [myPlugin, npmPackage],
});

# Plugins with options

It's also possible to pass custom parameters to plugins to make them more flexible.

const myPluginWithOptions = (editor, options) => {
  console.log(options);
  // { customField: 'customValue' }
};

const editor = grapesjs.init({
  container: '#gjs',
  plugins: [myPluginWithOptions],
  pluginsOpts: {
    [myPluginWithOptions]: {
      customField: 'customValue',
    },
  },
});

# Usage with TS

If you're using TypeScript, we recommend using the usePlugin helper for better type safety.

import grapesjs, { usePlugin } from 'grapesjs';
import type { Plugin } from 'grapesjs';

interface MyPluginOptions {
  opt1: string;
  opt2?: number;
}

const myPlugin: Plugin<MyPluginOptions> = (editor, options) => {
  // ...
};

grapesjs.init({
  // ...
  plugins: [
    // no need for `pluginsOpts`
    usePlugin(myPlugin, { opt1: 'A', opt2: 1 }),
  ],
});

# Dynamic plugin management

WARNING

Available starting with GrapesJS v0.23.1.

Plugins can also be added and removed dynamically at runtime via editor.Plugins.

This is useful when:

  • you want to enable/disable editor features on demand
  • you need to inspect which plugins are currently active
  • you want automatic cleanup of editor-level registrations added by a plugin
const editor = grapesjs.init({
  // ...
  plugins: [
    // Load plugin on init...
    { id: 'my-plugin-1', plugin: usePlugin(myPlugin, { opt1: 'A' }) }
  ],
});

// ... or add it dynamically
const plugin = editor.Plugins.add({
  id: 'my-plugin-2',
  plugin: usePlugin(myPlugin, { opt1: 'A' }),
});

const hasPlugin = !!editor.Plugins.get('my-plugin-2');
editor.Plugins.getAll();
editor.Plugins.remove('my-plugin-2');

GrapesJS stores active plugins in the editor.Plugins module, so each plugin can be identified and removed later.

For this reason, the object descriptor form requires an explicit id.

editor.Plugins.add({
  id: 'my-plugin',
  plugin: usePlugin(myPlugin, { opt1: 'A' }),
});

When possible, GrapesJS also tracks editor-level entities added during plugin execution and removes them automatically when the plugin is removed. This currently applies to runtime/editor configuration features such as blocks, component types, keymaps, etc.

The automatic cleanup is intentionally limited to editor-level registrations. It does not remove project data such as pages, components already added to the canvas, or any other persisted content.

If a plugin needs additional teardown logic, it can return a cleanup function.

const myPlugin: Plugin = (editor) => {
  const interval = setInterval(() => {
    // ...
  }, 1000);

  return ({ cleanup }) => {
    cleanup();
    clearInterval(interval);
  };
};

# Boilerplate

For fast plugin development, we highly recommend using grapesjs-cli (opens new window), which helps you avoid the hassle of setting up all the dependencies and configuration for development and builds (no need to touch Webpack or Babel configurations). For more information, check the repository.

← Symbols →