GrapesJS Skill
Quick Start
Initialize the editor:
import 'grapesjs/dist/css/grapes.min.css';
import grapesjs from 'grapesjs';
const editor = grapesjs.init({
container: '#gjs',
fromElement: true,
storageManager: false,
plugins: [],
});Core API Modules
Access modules from the editor instance:
editor.DomComponents // Component management (alias: editor.Components)
editor.BlockManager // Block management (alias: editor.Blocks)
editor.StyleManager // Style properties
editor.Panels // UI panels
editor.Commands // Command system
editor.Canvas // Canvas control
editor.StorageManager // Data persistence (alias: editor.Storage)
editor.DeviceManager // Responsive devices
editor.SelectorManager // CSS selectors/classes
editor.Modal // Modal dialogs
editor.Pages // Multi-page support
editor.I18n // Internationalization
editor.AssetManager // Asset/media management (alias: editor.Assets)
editor.LayerManager // Layer tree (alias: editor.Layers)
editor.TraitManager // Trait/settings (alias: editor.Traits)
editor.RichTextEditor // RTE customization
editor.Keymaps // Keyboard shortcuts
editor.UndoManager // Undo/Redo
editor.Parser // HTML/CSS parserKey Editor Methods
editor.getHtml() // Get HTML output
editor.getCss() // Get CSS output
editor.getJs() // Get JS output
editor.getProjectData() // Get full project JSON
editor.loadProjectData(json) // Load project from JSON
editor.getWrapper() // Root component
editor.getSelected() // Last selected component
editor.getSelectedAll() // All selected components
editor.select(component) // Select a component
editor.selectAdd(component) // Add to selection
editor.selectRemove(component)// Remove from selection
editor.addComponents(html) // Add components
editor.setComponents(html) // Replace components
editor.addStyle(css) // Add CSS rules
editor.setStyle(css) // Replace all CSS rules
editor.on(event, callback) // Listen to events
editor.off(event, callback) // Remove listener
editor.once(event, callback) // Listen once
editor.runCommand(id, opts) // Run command
editor.stopCommand(id, opts) // Stop command
editor.store() // Save to storage
editor.load() // Load from storage
editor.getDevice() // Get current device name
editor.setDevice('Mobile') // Switch device
editor.getDirtyCount() // Unsaved changes count
editor.clearDirtyCount() // Reset changes counter
editor.getContainer() // Editor container HTMLElement
editor.onReady(callback) // Run when editor is fully loaded
editor.destroy() // Destroy editor
editor.refresh() // Update editor dimensions
editor.setCustomRte(obj) // Replace built-in RTE
editor.setDragMode(mode) // 'absolute' | 'translate'Plugins
Plugins are functions executed on editor init. Always define custom component types inside plugins (necessary so types exist before templates are loaded from storage).
const myPlugin = (editor, options) => {
editor.DomComponents.addType('my-type', { /* ... */ });
editor.BlockManager.add('my-block', { /* ... */ });
};
grapesjs.init({
plugins: [myPlugin],
pluginsOpts: { [myPlugin]: { opt1: 'value' } },
});TypeScript Usage
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: [usePlugin(myPlugin, { opt1: 'A', opt2: 1 })],
});Default Commands
Built-in commands use core:* namespace. Full list in references/commands-reference.md. Key commands:
core:canvas-clear, core:component-delete, core:component-enter (select child), core:component-exit (select parent), core:component-next/prev, core:component-outline, core:component-offset, core:component-select, core:copy/core:paste, core:preview, core:fullscreen, core:open-code, core:open-layers, core:open-styles, core:open-traits, core:open-blocks, core:open-assets, core:undo/core:redo.
Editor Init Config Reference
Key grapesjs.init({...}) options:
grapesjs.init({
container: '#gjs', // Selector or HTMLElement
fromElement: false, // Load content from container
height: '100%', // Editor height
width: 'auto', // Editor width
projectData: {}, // Initial project data (skips storage load)
mediaCondition: 'max-width', // or 'min-width' for mobile-first
plugins: [],
pluginsOpts: {},
panels: { defaults: [] },
blockManager: { blocks: [], appendTo: '.container' },
layerManager: { appendTo: '.container' },
styleManager: { appendTo: '.container', sectors: [] },
selectorManager: { appendTo: '.container', componentFirst: false },
traitManager: { appendTo: '.container' },
storageManager: { type: 'local', autosave: true, autoload: true },
deviceManager: { devices: [] },
assetManager: { assets: [], upload: false },
canvas: {
scripts: [], // JS files to load in canvas iframe
styles: [], // CSS files to load in canvas iframe
},
keymaps: { defaults: {} }, // Custom keyboard shortcuts
});Common Pitfalls
1. Component scripts run in an isolated iframe
All component scripts execute inside the canvas iframe, NOT in the editor's document. You cannot reference external variables, editor APIs, or outer-scope libraries inside script. Use script-props to pass data. See references/components-js-reference.md.
2. find() only works after render, findType() works always
component.find('.my-class') uses CSS selectors and requires the component to be rendered in the canvas. Use component.findType('image') or component.closestType('section') when working with components before render (e.g., in init() hooks or plugins).
3. Don't put styles or scripts in blocks
Block content should be component-oriented. Declare styles in the component type defaults, not in the block content. Scripts belong in the component type definition, not in block HTML.
4. isComponent is NOT called for objects or data-gjs-type
When you add components via objects ({type: 'my-type'}) or HTML with data-gjs-type, the isComponent function is skipped. It only runs for plain HTML strings without data-gjs-type.
5. Component-scoped styles are grouped per type
Styles defined in defaults.styles are shared across all instances of that type and auto-removed only when ALL instances of that type are removed. Follow component-oriented styling: each type owns its own styles.
6. locked cascades to children
Setting locked: true on a component disables selection for it AND all its children. A child can opt out by explicitly setting its own locked: false.
7. propagate applies to NEW children only
The propagate array only affects components appended AFTER the property is set. Existing children are not retroactively updated.
8. UndoManager tracks components and CSS rules automatically
You don't need to manually add components or CSS rules to the UndoManager — they're auto-tracked. Use um.skip(() => {...}) for batch programmatic changes you don't want in the undo stack.
9. Aborting component removal
Listen to component:remove:before and set opts.abort = true to prevent deletion. Call the provided removeFn() later to complete it.
10. Canvas dependencies are NOT in exported HTML
Scripts/styles added via canvas.scripts / canvas.styles config are loaded in the editor's iframe but NOT included in editor.getHtml() output. You must include them separately in your final template.
Detailed References
- API Reference (components, blocks, commands, storage, events, traits, canvas, assets, layers, pages): See references/api-reference.md
- Core API (UndoManager, Canvas zoom/coords/drag, CssComposer, Keymaps, component properties like draggable/droppable/resizable/locked/selectable): See references/core-api-reference.md
- Components & JS + Symbols (component scripts, script-props, dependencies, symbols/instances, overrides): See references/components-js-reference.md
- Style Customization (Style Manager, theming, CSS variables, custom types): See references/style-customization.md
- Traits & Settings (built-in types, custom types, custom UI, categories, i18n): See references/traits-reference.md
- Canvas & Spots (canvas spots, custom overlays, disabling built-in spots): See references/canvas-reference.md
- Storage Deep Dive (local, remote, custom storage, inline, project data): See references/storage-reference.md
- Commands Deep Dive (stateful commands, extending, events, aborting): See references/commands-reference.md
- UI Layout Patterns (panels, layers, sidebar, switchers): See references/ui-layout-patterns.md
- MJML Plugin (email builder, MJML components, export MJML/HTML, custom components, preMjml/postMjml): See references/mjml-plugin-reference.md