Guía de componentes personalizados GrapesJS (2026)

Los componentes definen el comportamiento, no solo el marcado

Un componente GrapesJS es un modelo tipado con valores predeterminados, rasgos (ajustes editables), y una vista opcional. Registras uno con DomComponents.addType. Esta guía construye un componente personalizado con un y muestra cómo se mapea el HTML importado en él.

1. Registrar un tipo de componente

editor.DomComponents.addType('rating', {
  // Map matching HTML onto this type when content is loaded.
  isComponent: (el) => el.classList?.contains('rating') && { type: 'rating' },

  model: {
    defaults: {
      tagName: 'div',
      classes: ['rating'],
      // Editable settings shown in the trait panel:
      traits: [
        { type: 'number', name: 'stars', label: 'Stars', min: 1, max: 5 },
      ],
      stars: 5,
    },
  },
});

2. Reaccionar a los cambios de rasgos en una vista

editor.DomComponents.addType('rating', {
  model: {
    defaults: { tagName: 'div', classes: ['rating'], stars: 5,
      traits: [{ type: 'number', name: 'stars', min: 1, max: 5 }] },
  },
  view: {
    init() {
      this.listenTo(this.model, 'change:stars', this.render);
    },
    onRender() {
      const n = this.model.get('stars');
      this.el.textContent = '★'.repeat(n) + '☆'.repeat(5 - n);
    },
  },
});

3. Exponerlo como un bloque

editor.BlockManager.add('rating', {
  label: 'Rating',
  category: 'Widgets',
  content: { type: 'rating', stars: 4 },
});

Porque isComponent reconoce .rating elementos, carga el HTML guardado recrea el componente — rasgos y comportamiento intactos.

Errores comunes

Los componentes personalizados fallan de formas predecibles. Si tu isComponent no devuelve un valor de truthy (normalmente { type }) por coincidir con el DOM, el HTML cargado no se asignará a tu tipo y los rasgos desaparecerán al recargar. Si la vista no listenTo muestra el evento del change:<trait> modelo, las ediciones en el panel de rasgos no se volverán a renderizar. Rerenderizar dentro de un handler que a su vez provoca un cambio puede causar un bucle infinito: actualizar el DOM directamente en lugar de llamar a un renderizado completo cuando sea posible. Y ponlo draggabledeliberadamentedroppable para que tu componente solo pueda colocarse donde tenga sentido.

Requisitos previos

Necesitas un editor GrapesJS funcionando y JavaScript básico. Los componentes se registran con DomComponents.addType; las tres piezas son detección (),isComponent el modelo (valores predeterminados + rasgos) y una vista opcional (comportamiento en lienzo).

Modelo: valores predeterminados, rasgos y restricciones

El modelo define qué es el componente. Más allá de los rasgos, puedes limitar donde pueda ir y lo que acepta con draggable, droppable, y editable:

editor.DomComponents.addType('rating', {
  isComponent: (el) => el.classList?.contains('rating') && { type: 'rating' },
  model: {
    defaults: {
      tagName: 'div',
      classes: ['rating'],
      droppable: false,
      traits: [{ type: 'number', name: 'stars', min: 1, max: 5 }],
      stars: 5,
    },
  },
});

Vista: reaccionar a cambios de rasgos

view: {
  init() { this.listenTo(this.model, 'change:stars', this.render); },
  onRender() {
    const n = this.model.get('stars');
    this.el.textContent = '★'.repeat(n) + '☆'.repeat(5 - n);
  },
}

Por qué importaIsComponent

isComponent se ejecuta cuando se carga HTML en el editor. Devolviendo el tipo El objeto para emparejar elementos es lo que permite que el marcado guardado se rehidrate en tu componente con sus rasgos y comportamiento intactos — sin él, una recarga hace que tu componente vuelva a funcionar a HTML simple.

Mejores prácticas

Mantén el modelo declarativo y pon el comportamiento en la vista. Evita activar un full render dentro de un gestor de cambios que a su vez causa un cambio — actualiza el DOM directamente a Evita los bucles. Establecer draggable/droppable deliberadamente para que sea El componente solo puede colocarse donde tenga sentido. Exponer rasgos significativos para que los editores puede configurar el componente sin necesidad de código.

Próximos pasos

Componentes superficiales como unidades arrastrables en el Guía de bloques personalizados, paquete en un plugin personalizado, o navega por los plugins GrapesJS en GJS. Mercado.

Preguntas frecuentes

¿Cómo puedo crear un componente personalizado en GrapesJS?

Llamada editor.DomComponents.addType(type, { isComponent, model, view }) — definiendo la detección, los valores por defecto/rasgos y el comportamiento del lienzo.

¿Qué son los rasgos?

Los rasgos son los ajustes editables que se muestran en el panel de rasgos para un seleccionado componente; Decláralos en model.defaults.traits.

¿Cómo funciona isComponent?

Recibe un elemento DOM y devuelve un valor truthy (a menudo { type }) cuando ese elemento debe convertirse en tu componente, por lo que importado HTML se corresponde con tu tipo.