Cómo añadir un bloque personalizado en GrapesJS (2026)

Los bloques son los que los usuarios arrastran al lienzo

Un bloque es un fragmento reutilizable que aparece en el panel de bloques de GrapesJS. Añades ellos a través del Jefe de Bloque. Esta guía añade bloques HTML simples y los agrupa en categorías, les da iconos y respalda uno con un componente reutilizable.

1. Añadir un bloque básico

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>`,
});

Puede content ser una cadena HTML (arriba) o una definición de componente Objetivo de tener más control.

2. Añadir un icono (medios)

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 acepta SVG en línea o una <img> etiqueta y es mostrado como la miniatura en bloque.

3. Retroceder un bloque con un componente reutilizable

// 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
});

Al eliminar este bloque, se crea una instancia de tu pricing-card componente, así que su comportamiento y rasgos vienen automáticamente.

Consejos

Haz que los bloques sean agradables de usar. Agrupa los bloques relacionados con la category propiedad para que el panel se mantenga organizado, y asigna a cada uno un media SVG para que los usuarios lo reconozcan de un vistazo. Para cualquier cosa más allá de un solo elemento, establece el bloque content en una definición de componente ({ type: '…' }) respaldada por un componente registrado, de modo que el bloque tenga sus propias características y comportamiento en lugar de volcar HTML inerte. Puedes controlar el orden y el panel de destino a través de las opciones de añadir, y puedes añadir bloques desde dentro de un plugin para que toda una biblioteca se instale en una sola línea.

Requisitos previos

Necesitas un editor GrapesJS en funcionamiento. Los bloques se añaden a través del Gestor de Bloques, que Puedes llamar en cualquier momento después grapesjs.init , ya sea desde tu código de aplicación o desde Dentro de un plugin, así que toda una biblioteca se instala en una sola línea.

Opciones de bloques que merece la pena conocer

Más allá labelde , category, y content, un bloque puede Establece una media miniatura, controla si al soltarla seleccionas la nueva componente (select: true), y conjunto attributes para el panel Ítem:

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' },
});

Bloques respaldados por componentes

Para cualquier cosa que no sea HTML inerte, configura el bloque content como un componente Definición cuyo type coincide con un componente con el que te registraste DomComponents.addType. Al soltar el bloque, se crea ese componente, así que Sus rasgos y comportamientos aparecen automáticamente.

Añadir toda una biblioteca de una vez

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' }));

Mejores prácticas

Bloques relacionados con el grupo para category que el panel se mantenga organizado, y dar cada bloque es un icono reconocible media . Mantén el HTML de bloque pequeño y semántica; Convertir el comportamiento complejo en un componente de respaldo en lugar de un contenido gigante cuerda. Prefijo los identificadores de bloque para evitar colisiones con plugins.

Resolución de problemas

Que un bloque no aparezca normalmente significa que se añade antes que el bloque El gerente está listo o bajo una categoría que está colapsada. Dejarlo caer sí Nada útil suele significar que el componente type referenciado no lo sea Registrado.

Próximos pasos

Aprende a definir los tipos de componentes que los bloques pueden referenciar en el Guía de componentes personalizados, o wrap tus bloques en un reutilizable Plugin GrapesJS. Explora la catálogo completo de plugins GrapesJS o Plugins de biblioteca de bloques en GJS. Mercado.

Preguntas frecuentes

¿Cómo añado un bloque en GrapesJS?

Llama editor.BlockManager.add(id, { label, category, content }); el El bloque aparece en el panel listo para arrastrarse.

¿Cómo agrupo los bloques en categorías?

Establezca la category propiedad — los bloques con la misma categoría se agrupan en el panel.

¿Puede un bloque insertar un componente reutilizable?

Sí — establecido content a una definición de componente cuyo type coincide con un componente con DomComponents.addTypeel que te registraste.