How to add a custom block in GrapesJS (2026)

Blocks are what users drag onto the canvas

A block is a reusable chunk that appears in the GrapesJS blocks panel. You add them through the Block Manager. This guide adds plain HTML blocks, groups them into categories, gives them icons, and backs one with a reusable component.

1. Add a basic block

editor.BlockManager.add('cta-banner', {
  label: 'CTA Banner',
  category: 'Sections',
  content: `
    <section class="cta py-16 text-center">
      <h2>Ready to start?</h2>
      <a href="#">Get started</a>
    </section>`,
});

The content can be an HTML string (above) or a component definition object for more control.

2. Add an icon (media)

editor.BlockManager.add('image-block', {
  label: 'Image',
  category: 'Basic',
  media: '<svg viewBox="0 0 24 24"><path d="M4 5h16v14H4z"/></svg>',
  content: { type: 'image' },
});

media accepts inline SVG or an <img> tag and is shown as the block thumbnail.

3. Back a block with a reusable component

// content references a custom component type you registered:
editor.BlockManager.add('pricing-card', {
  label: 'Pricing card',
  category: 'Sections',
  content: { type: 'pricing-card' },   // see the custom-components guide
});

Dropping this block creates an instance of your pricing-card component, so its behavior and traits come along automatically.

Tips

Make blocks pleasant to use. Group related blocks with the category property so the panel stays organised, and give each a media SVG so users recognise it at a glance. For anything beyond a single element, set the block content to a component definition ({ type: '…' }) backed by a registered component, so the block carries its own traits and behaviour rather than dumping inert HTML. You can control ordering and the target panel through the add options, and you can add blocks from inside a plugin so a whole library installs in one line.

Prerequisites

You need a running GrapesJS editor. Blocks are added through the Block Manager, which you can call any time after grapesjs.init — from your app code or from inside a plugin so a whole library installs in one line.

Block options worth knowing

Beyond label, category, and content, a block can set a media thumbnail, control whether dropping it selects the new component (select: true), and set attributes for the panel item:

editor.BlockManager.add('image-card', {
  label: 'Image card',
  category: 'Cards',
  media: '<svg viewBox="0 0 24 24"><path d="M4 5h16v14H4z"/></svg>',
  select: true,
  content: { type: 'image' },
});

Component-backed blocks

For anything beyond inert HTML, set the block content to a component definition whose type matches a component you registered with DomComponents.addType. Dropping the block then creates that component, so its traits and behaviour come along automatically.

Add a whole library at once

const blocks = [
  { id: 'h1', label: 'Heading', content: '<h1>Title</h1>' },
  { id: 'p', label: 'Paragraph', content: '<p>Text</p>' },
];
blocks.forEach((b) => editor.BlockManager.add(b.id, { ...b, category: 'Basic' }));

Best practices

Group related blocks with category so the panel stays organised, and give every block a recognisable media icon. Keep block HTML small and semantic; push complex behaviour into a backing component rather than a giant content string. Prefix block ids to avoid collisions with plugins.

Troubleshooting

A block doesn't appear usually means it's added before the Block Manager is ready or under a category that's collapsed. Dropping it does nothing useful often means the referenced component type isn't registered.

Next steps

Learn how to define the component types blocks can reference in the custom components guide, or wrap your blocks into a reusable GrapesJS plugin. Browse the full GrapesJS plugins catalog or block library plugins on GJS.Market.

FAQ

How do I add a block in GrapesJS?

Call editor.BlockManager.add(id, { label, category, content }); the block appears in the panel ready to drag.

How do I group blocks into categories?

Set the category property — blocks with the same category are grouped in the panel.

Can a block insert a reusable component?

Yes — set content to a component definition whose type matches a component you registered with DomComponents.addType.