grapesjs Documentation

Free and Open source Web Builder Framework. Next generation tool for building templates without coding

RAW Doc

File: README.md

[GrapesJS](http://grapesjs.com)




If you looking to embed the Studio editor in your application, we now offer the Studio SDK, a ready-to-use visual builder that's easy to embed in external applications, with GrapesJS team support included.

GrapesJS is a free and open source Web Builder Framework which helps building HTML templates, faster and easily, to be delivered in sites, newsletters or mobile apps. Mainly, GrapesJS was designed to be used inside a CMS to speed up the creation of dynamic templates. To better understand this concept check the image below

Generally any 'template system', that you'd find in various applications like CMS, is composed by the structure (HTML), style (CSS) and variables, which are then replaced with other templates and contents on server-side and rendered on client.

This demos show examples of what is possible to achieve:
Webpage Demo - http://grapesjs.com/demo.html
Newsletter Demo - http://grapesjs.com/demo-newsletter-editor.html

Table of contents

Features

Blocks Style Manager Layer Manager
Code Viewer Asset Manager
  • Local and remote storage

  • Default built-in commands (basically for creating and managing different components)

Download

  • CDNs
    • UNPKG (resolves to the latest version)
      • https://unpkg.com/grapesjs
      • https://unpkg.com/grapesjs/dist/css/grapes.min.css
    • CDNJS (replace X.X.X with the current version)
      • https://cdnjs.cloudflare.com/ajax/libs/grapesjs/X.X.X/grapes.min.js
      • https://cdnjs.cloudflare.com/ajax/libs/grapesjs/X.X.X/css/grapes.min.css
  • NPM
    • npm i grapesjs
  • GIT
    • git clone https://github.com/GrapesJS/grapesjs.git

For the development purpose you should follow instructions below.

Usage

html
<link rel="stylesheet" href="path/to/grapes.min.css" />
<script src="path/to/grapes.min.js"></script>



<script type="text/javascript">
  var editor = grapesjs.init({
    container: '#gjs',
    components: 'Hello world!',
    style: '.txt-red{color: red}',
  });
</script>

For a more practical example I'd suggest looking up the code inside this demo: http://grapesjs.com/demo.html

Development

Follow the Contributing Guide.

Documentation

Check the getting started guide here: Documentation

API

API References could be found here: API-Reference

Testing

sh
$ pnpm test

Plugins

Official Plugins | Community Plugins

Wrappers

  • @grapesjs/react - GrapesJS wrapper for React that allows you to build custom and declarative UI for your editor.

Extensions

Presets

Find out more about plugins here: Creating plugins

Support

If you like the project and you wish to see it grow, please consider supporting us with a donation of your choice or become a backer/sponsor via Open Collective




Thanks to BrowserStack for providing us browser testing services

License

BSD 3-clause


File: docs/api/asset.md

Asset

Properties

  • type String Asset type, eg. 'image'.
  • src String Asset URL, eg. 'https://.../image.png'.

getType

Get asset type.

Examples

javascript
// Asset: { src: 'https://.../image.png', type: 'image' }
asset.getType(); // -> 'image'

Returns String

getSrc

Get asset URL.

Examples

javascript
// Asset: { src: 'https://.../image.png'  }
asset.getSrc(); // -> 'https://.../image.png'

Returns String

getFilename

Get filename of the asset (based on src).

Examples

javascript
// Asset: { src: 'https://.../image.png' }
asset.getFilename(); // -> 'image.png'
// Asset: { src: 'https://.../image' }
asset.getFilename(); // -> 'image'

Returns String

getExtension

Get extension of the asset (based on src).

Examples

javascript
// Asset: { src: 'https://.../image.png' }
asset.getExtension(); // -> 'png'
// Asset: { src: 'https://.../image' }
asset.getExtension(); // -> ''

Returns String


File: docs/api/assets.md

Assets

You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object

js
const editor = grapesjs.init({
 assetManager: {
   // options
 }
})

Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance

js
const assetManager = editor.AssetManager;

Available Events

  • asset:add New asset added to the collection. The Asset is passed as an argument to the callback.
javascript
editor.on('asset:add', (asset) => { ... });
  • asset:remove Asset removed from the collection. The Asset is passed as an argument to the callback.
javascript
editor.on('asset:remove', (asset) => { ... });
  • asset:update Asset updated. The Asset and the object containing changes are passed as arguments to the callback.
javascript
editor.on('asset:update', (asset, updatedProps) => { ... });
  • asset:open Asset Manager opened.
javascript
editor.on('asset:open', () => { ... });
  • asset:close Asset Manager closed.
javascript
editor.on('asset:close', () => { ... });
  • asset:upload:start Asset upload start.
javascript
editor.on('asset:upload:start', () => { ... });
  • asset:upload:end Asset upload end.
javascript
editor.on('asset:upload:end', (result) => { ... });
  • asset:upload:error Asset upload error.
javascript
editor.on('asset:upload:error', (error) => { ... });
  • asset:upload:response Asset upload response.
javascript
editor.on('asset:upload:response', (res) => { ... });
javascript
editor.on('asset:custom', ({ container, assets, ... }) => { ... });
  • asset Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback.
javascript
editor.on('asset', ({ event, model, ... }) => { ... });

Methods

open

Open the asset manager.

Parameters

  • options Object? Options for the asset manager. (optional, default {})

    • options.types Array<String> Types of assets to show. (optional, default ['image'])
    • options.select Function? Type of operation to perform on asset selection. If not specified, nothing will happen.

Examples

javascript
assetManager.open({
 select(asset, complete) {
   const selected = editor.getSelected();
   if (selected && selected.is('image')) {
     selected.addAttributes({ src: asset.getSrc() });
     // The default AssetManager UI will trigger `select(asset, false)` on asset click
     // and `select(asset, true)` on double-click
     complete && assetManager.close();
   }
 }
});
// with your custom types (you should have assets with those types declared)
assetManager.open({ types: ['doc'], ... });

close

Close the asset manager.

Examples

javascript
assetManager.close();

isOpen

Checks if the asset manager is open

Examples

javascript
assetManager.isOpen(); // true | false

Returns Boolean

add

Add new asset/s to the collection. URLs are supposed to be unique

Parameters

Examples

javascript
// As strings
assetManager.add('http://img.jpg');
assetManager.add(['http://img.jpg', './path/to/img.png']);

// Using objects you can indicate the type and other meta informations
assetManager.add({
 // type: 'image',	// image is default
	src: 'http://img.jpg',
	height: 300,
width: 200,
});
assetManager.add([{ src: 'img2.jpg' }, { src: 'img2.png' }]);

Returns Asset

get

Return asset by URL

Parameters

Examples

javascript
const asset = assetManager.get('http://img.jpg');

Returns (Asset | null)

getAll

Return the global collection, containing all the assets

Returns Collection<Asset>

getAllVisible

Return the visible collection, which contains assets actually rendered

Returns Collection<Asset>

remove

Remove asset

Parameters

  • asset (String | Asset) Asset or asset URL
  • opts RemoveOptions?

Examples

javascript
const removed = assetManager.remove('http://img.jpg');
// or by passing the Asset
const asset = assetManager.get('http://img.jpg');
assetManager.remove(asset);

Returns Asset Removed asset

getContainer

Return the Asset Manager Container

Returns HTMLElement


File: docs/api/block.md

Block

Properties

  • label String Block label, eg. My block
  • content (String | Object) The content of the block. Might be an HTML string or a Component Definition
  • media String? HTML string for the media/icon of the block, eg. <svg ..., editor.getWrapper().append(block.get('content'))
  • attributes Object? Block attributes to apply in the view element

getId

Get block id

Returns String

getLabel

Get block label

Returns String

getMedia

Get block media

Returns String

getContent

Get block content

Returns (Object | String | Array<(Object | String)>)

getDragDef

Get block component dragDef

Returns ComponentDefinition

getCategoryLabel

Get block category label

Returns String


File: docs/api/block_manager.md

Blocks

You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object

js
const editor = grapesjs.init({
 blockManager: {
   // options
 }
})

Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.

js
// Listen to events
editor.on('block:add', (block) => { ... });

// Use the API
const blockManager = editor.Blocks;
blockManager.add(...);

Available Events

  • block:add New block added to the collection. The Block is passed as an argument to the callback.
javascript
editor.on('block:add', (block) => { ... });
  • block:remove Block removed from the collection. The Block is passed as an argument to the callback.
javascript
editor.on('block:remove', (block) => { ... });
  • block:remove:before Event triggered before Block remove.
javascript
editor.on('block:remove:before', (block, remove, opts) => { ... });
  • block:update Block updated. The Block and the object containing changes are passed as arguments to the callback.
javascript
editor.on('block:update', (block, updatedProps) => { ... });
  • block:drag:start Started dragging block. The Block is passed as an argument.
javascript
editor.on('block:drag:start', (block) => { ... });
  • block:drag The block is dragging. The Block is passed as an argument.
javascript
editor.on('block:drag', (block) => { ... });
  • block:drag:stop Dragging of the block is stopped. The dropped Component (if dropped successfully) and the Block are passed as arguments.
javascript
editor.on('block:drag:stop', (component, block) => { ... });
  • block:category:update Block category updated.
javascript
editor.on('block:category:update', ({ category, changes }) => { ... });
javascript
editor.on('block:custom', ({ container, blocks, ... }) => { ... });
  • block Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback.
javascript
editor.on('block', ({ event, model, ... }) => { ... });
  • BlocksEventCallback

getConfig

Get configuration object

Returns Object

add

Add new block.

Parameters

  • id String Block ID
  • props Block Block properties
  • opts (optional, default {})

Examples

javascript
blockManager.add('h1-block', {
  label: 'Heading',
  content: '<h1>Put your title here</h1>',
  category: 'Basic',
  attributes: {
    title: 'Insert h1 block'
  }
});

Returns Block Added block

get

Get the block by id.

Parameters

Examples

javascript
const block = blockManager.get('h1-block');
console.log(JSON.stringify(block));
// {label: 'Heading', content: '<h1>Put your ...', ...}

Returns Block

getAll

Return all blocks.

Examples

javascript
const blocks = blockManager.getAll();
console.log(JSON.stringify(blocks));
// [{label: 'Heading', content: '<h1>Put your ...'}, ...]

Returns Collection<Block>

getAllVisible

Return the visible collection, which containes blocks actually rendered

Returns Collection<Block>

remove

Remove block.

Parameters

  • block (String | Block) Block or block ID
  • opts (optional, default {})

Examples

javascript
const removed = blockManager.remove('BLOCK_ID');
// or by passing the Block
const block = blockManager.get('BLOCK_ID');
blockManager.remove(block);

Returns Block Removed block

getCategories

Get all available categories.
It's possible to add categories only within blocks via 'add()' method

Returns (Array | Collection)

getContainer

Return the Blocks container element

Returns HTMLElement

getDragBlock

Returns currently dragging block.
Updated when the drag starts and cleared once it's done.

Returns (Block | undefined)

getBlocksByCategory

Get blocks by category.

Parameters

Examples

javascript
blockManager.getBlocksByCategory();
// Returns an array of items of this type
// > { category?: Category; items: Block[] }

// NOTE: The item without category is the one containing blocks without category.

// You can also get the same output format by passing your own array of Blocks
const myFilteredBlocks: Block[] = [...];
blockManager.getBlocksByCategorymyFilteredBlocks

Returns **Array**

render

Render blocks

Parameters

  • blocks Array Blocks to render, without the argument will render all global blocks

  • opts Object Options (optional, default {})

    • opts.external Boolean? Render blocks in a new container (HTMLElement will be returned)
    • opts.ignoreCategories Boolean? Render blocks without categories

Examples

javascript
// Render all blocks (inside the global collection)
blockManager.render();

// Render new set of blocks
const blocks = blockManager.getAll();
const filtered = blocks.filter(block => block.get('category') == 'sections')

blockManager.render(filtered);
// Or a new set from an array
blockManager.render([
 {label: 'Label text', content: 'Content'}
]);

// Back to blocks from the global collection
blockManager.render();

// You can also render your blocks outside of the main block container
const newBlocksEl = blockManager.render(filtered, { external: true });
document.getElementById('some-id').appendChild(newBlocksEl);

Returns HTMLElement Rendered element


File: docs/api/canvas.md

Canvas

You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object

js
const editor = grapesjs.init({
 canvas: {
   // options
 }
})

Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.

js
// Listen to events
editor.on('canvas:drop', () => { ... });

// Use the API
const canvas = editor.Canvas;
canvas.setCoords(...);

Available Events

  • canvas:dragenter Something is dragged inside the canvas. DataTransfer instance and dragged content are passed as arguments.

  • canvas:dragover Something is dragging on the canvas. Triggering event is passed as an argument.

  • canvas:dragend When a drag operation is ended, triggering event is passed as an argument.

  • canvas:dragdata On any dataTransfer parse, DataTransfer instance and the result are passed as arguments. By changing result.content you're able to customize what is dropped.

  • canvas:drop Something is dropped in canvas, DataTransfer instance and the dropped model are passed as arguments.

  • canvas:spot Spots updated.

javascript
editor.on('canvas:spot', () => {
 console.log('Spots', editor.Canvas.getSpots());
});
  • canvas:spot:add New canvas spot added.
javascript
editor.on('canvas:spot:add', ({ spot }) => {
 console.log('Spot added', spot);
});
  • canvas:spot:update Canvas spot updated.
javascript
editor.on('canvas:spot:update', ({ spot }) => {
 console.log('Spot updated', spot);
});
  • canvas:spot:remove Canvas spot removed.
javascript
editor.on('canvas:spot:remove', ({ spot }) => {
 console.log('Spot removed', spot);
});
  • canvas:coords Canvas coordinates updated.
javascript
editor.on('canvas:coords', () => {
 console.log('Canvas coordinates updated:', editor.Canvas.getCoords());
});
  • canvas:zoom Canvas zoom updated.
javascript
editor.on('canvas:zoom', () => {
 console.log('Canvas zoom updated:', editor.Canvas.getZoom());
});
  • canvas:pointer Canvas pointer updated.
javascript
editor.on('canvas:pointer', () => {
 console.log('Canvas pointer updated:', editor.Canvas.getPointer());
});
  • canvas:refresh Canvas was refreshed to update elements on top, like spots/tools (eg. via editor.Canvas.refresh() or on frame resize).
javascript
editor.on('canvas:refresh', (canvasRefreshOptions) => {
 console.log('Canvas refreshed with options:', canvasRefreshOptions);
});
  • canvas:update Canvas was updated.

  • canvas:tools:update Canvas tools were updated.

  • canvas:move:start Canvas move started.

  • canvas:move Canvas is moving.

  • canvas:move:end Canvas move ended.

  • canvas:frame:load Frame loaded in canvas. The event is triggered right after iframe's onload.

javascript
editor.on('canvas:frame:load', ({ window }) => {
 console.log('Frame loaded', window);
});
  • canvas:frame:load:head Frame head loaded in canvas. The event is triggered right after iframe's finished to load the head elements (eg. scripts)
javascript
editor.on('canvas:frame:load:head', ({ window }) => {
 console.log('Frame head loaded', window);
});
  • canvas:frame:load:body Frame body loaded in canvas. The event is triggered when the body is rendered with components.
javascript
editor.on('canvas:frame:load:body', ({ window }) => {
 console.log('Frame completed the body render', window);
});
  • canvas:frame:unload Frame is unloading from the canvas.
javascript
editor.on('canvas:frame:unload', ({ frame }) => {
 console.log('Unloading frame', frame);
});

getConfig

Get configuration object

Returns Object

getElement

Get the canvas element

Returns HTMLElement

getFrameEl

Get the main frame element of the canvas

Returns HTMLIFrameElement

getWindow

Get the main frame window instance

Returns Window

getDocument

Get the main frame document element

Returns HTMLDocument

getBody

Get the main frame body element

Returns HTMLBodyElement

setCustomBadgeLabel

Set custom badge naming strategy

Parameters

Examples

javascript
canvas.setCustomBadgeLabel(function(component){
 return component.getName();
});

getRect

Get canvas rectangular data

Returns Object

startDrag

Start custom drag-and-drop process.

Parameters

  • dragSource DragSource<Component> The source object for the drag operation, containing the component being dragged.

Examples

javascript
// as component definition
canvas.startDrag({
 content: { type: 'my-component' }
});
// as HTML
canvas.startDrag({
 content: '...'
});

endDrag

Ends the drag-and-drop process, resetting the drag source and clearing any drag results.
This method can be used to finalize custom drag-and-drop content operations.

Examples

javascript
canvas.startDrag({...});
// ... drag finished ...
canvas.endDrag();

hasFocus

Check if the canvas is focused

Returns Boolean

scrollTo

Scroll canvas to the element if it's not visible. The scrolling is
executed via scrollIntoView API and options of this method are
passed to it. For instance, you can scroll smoothly by using
{ behavior: 'smooth' }.

Parameters

  • el (HTMLElement | Component)

  • opts Object Options, same as options for scrollIntoView (optional, default {})

    • opts.force Boolean Force the scroll, even if the element is already visible (optional, default false)

Examples

javascript
const selected = editor.getSelected();
// Scroll smoothly (this behavior can be polyfilled)
canvas.scrollTo(selected, { behavior: 'smooth' });
// Force the scroll, even if the element is already visible
canvas.scrollTo(selected, { force: true });

setZoom

Set canvas zoom value

Parameters

  • value Number The zoom value, from 0 to 100
  • opts SetZoomOptions (optional, default {})

Examples

javascript
canvas.setZoom(50); // set zoom to 50%

Returns this

getZoom

Get canvas zoom value

Examples

javascript
canvas.setZoom(50); // set zoom to 50%
const zoom = canvas.getZoom(); // 50

Returns Number

setCoords

Set canvas position coordinates

Parameters

  • x Number Horizontal position
  • y Number Vertical position
  • opts ToWorldOption (optional, default {})

Examples

javascript
canvas.setCoords(100, 100);

Returns this

getCoords

Get canvas position coordinates

Examples

javascript
canvas.setCoords(100, 100);
const coords = canvas.getCoords();
// { x: 100, y: 100 }

Returns Object Object containing coordinates

getLastDragResult

Get the last created Component from a drag & drop to the canvas.

Returns (Component | undefined)

addSpot

Add or update canvas spot.

Parameters

  • props Object Canvas spot properties.
  • opts AddOptions (optional, default {})

Examples

javascript
// Add new canvas spot
const spot = canvas.addSpot({
 type: 'select', // 'select' is one of the built-in spots
 component: editor.getSelected(),
});

// Add custom canvas spot
const spot = canvas.addSpot({
 type: 'my-custom-spot',
 component: editor.getSelected(),
});
// Update the same spot by reusing its ID
canvas.addSpot({
 id: spot.id,
 component: anotherComponent,
});

Returns CanvasSpot

getSpots

Get canvas spots.

Parameters

  • spotProps Object? Canvas spot properties for filtering the result. With no properties, all available spots will be returned. (optional, default {})

Examples

javascript
canvas.addSpot({ type: 'select', component: cmp1 });
canvas.addSpot({ type: 'select', component: cmp2 });
canvas.addSpot({ type: 'target', component: cmp3 });

// Get all spots
const allSpots = canvas.getSpots();
allSpots.length; // 3

// Get all 'select' spots
const allSelectSpots = canvas.getSpots({ type: 'select' });
allSelectSpots.length; // 2

Returns Array<CanvasSpot>

removeSpots

Remove canvas spots.

Parameters

  • spotProps (Object | Array<CanvasSpot>)? Canvas spot properties for filtering spots to remove or an array of spots to remove. With no properties, all available spots will be removed. (optional, default {})

Examples

javascript
canvas.addSpot({ type: 'select', component: cmp1 });
canvas.addSpot({ type: 'select', component: cmp2 });
canvas.addSpot({ type: 'target', component: cmp3 });

// Remove all 'select' spots
canvas.removeSpots({ type: 'select' });

// Remove spots by an array of canvas spots
const filteredSpots = canvas.getSpots().filter(spot => myCustomCondition);
canvas.removeSpots(filteredSpots);

// Remove all spots
canvas.removeSpots();

Returns Array<CanvasSpot>

hasCustomSpot

Check if the built-in canvas spot has a declared custom rendering.

Parameters

  • type String Built-in canvas spot type

Examples

javascript
grapesjs.init({
 // ...
 canvas: {
   // avoid rendering the built-in 'target' canvas spot
   customSpots: { target: true }
 }
});
// ...
canvas.hasCustomSpot('select'); // false
canvas.hasCustomSpot('target'); // true

Returns Boolean

getWorldRectToScreen

Transform a box rect from the world coordinate system to the screen one.

Parameters

Returns Object

refresh

Update canvas for spots/tools positioning.

Parameters

  • opts Object? Options. (optional, default {})

    • opts.spots Object Update the position of spots. (optional, default false)

File: docs/api/canvas_spot.md

CanvasSpot

Canvas spots are elements drawn on top of the canvas. They can be used to represent anything you
might need but the most common use case of canvas spots is rendering information and managing
components rendered in the canvas.
Read here for more information about Canvas Spots

Properties

  • id String Spot ID.
  • type String Spot type.
  • component Component? Component to which the spot will be attached.
  • componentView ComponentView? ComponentView to which the spot will be attached.
  • boxRect Object? Fixed box rect of the spot, eg. { width: 100, height: 100, x: 0, y: 0 }.

getBoxRect

Get the box rect of the spot.

Parameters

  • opts Object (optional, default {})

Examples

javascript
canvasSpot.getBoxRect();
// { width: 100, height: 50, x: 0, y: 0 }

Returns Object The box rect object

getStyle

Get the style object of the spot.

Parameters

  • opts Object (optional, default {})

Examples

javascript
canvasSpot.getStyle();
// { width: '100px', height: '...', ... }

Returns CSSStyleDeclaration [opts]

isType

Check the spot type.

Parameters

Examples

javascript
canvasSpot.isType('select');

Returns Boolean


File: docs/api/commands.md

Commands

You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object

js
const editor = grapesjs.init({
 commands: {
   // options
 }
})

Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.

js
// Listen to events
editor.on('run', () => { ... });

// Use the API
const commands = editor.Commands;
commands.add(...);

Available Events

  • command:run Triggered on run of any command.
javascript
editor.on('command:run', ({ id, result, options }) => {
 console.log('Command id', id, 'command result', result);
});
  • command:run:COMMAND_ID Triggered on run of a specific command.
javascript
editor.on('command:run:my-command', ({ result, options }) => { ... });
  • command:run:before:COMMAND_ID Triggered before the command is called.
javascript
editor.on('command:run:before:my-command', ({ options }) => { ... });
  • command:abort:COMMAND_ID Triggered when the command execution is aborted.
javascript
editor.on('command:abort:my-command', ({ options }) => { ... });

// The command could be aborted during the before event
editor.on('command:run:before:my-command', ({ options }) => {
 if (someCondition) {
   options.abort = true;
 }
});
  • command:stop Triggered on stop of any command.
javascript
editor.on('command:stop', ({ id, result, options }) => {
 console.log('Command id', id, 'command result', result);
});
  • command:stop:COMMAND_ID Triggered on stop of a specific command.
javascript
editor.on('command:run:my-command', ({ result, options }) => { ... });
  • command:stop:before:COMMAND_ID Triggered before the command is called to stop.
javascript
editor.on('command:stop:before:my-command', ({ options }) => { ... });

Methods

add

Add new command to the collection

Parameters

  • id string Command's ID
  • command (Object | Function) Object representing your command,
    By passing just a function it's intended as a stateless command
    (just like passing an object with only run method).

Examples

javascript
commands.add('myCommand', {
	run(editor, sender) {
		alert('Hello world!');
	},
	stop(editor, sender) {
	},
});
// As a function
commands.add('myCommand2', editor => { ... });

Returns this

get

Get command by ID

Parameters

Examples

javascript
var myCommand = commands.get('myCommand');
myCommand.run();

Returns Object Object representing the command

extend

Extend the command. The command to extend should be defined as an object

Parameters

  • id string Command's ID
  • cmd CommandObject (optional, default {})
  • Object Object with the new command functions

Examples

javascript
commands.extend('old-command', {
 someInnerFunction() {
 // ...
 }
});

Returns this

has

Check if command exists

Parameters

Returns Boolean

getAll

Get an object containing all the commands

Returns Object

run

Execute the command

Parameters

  • id String Command ID
  • options Object Options (optional, default {})

Examples

javascript
commands.run('myCommand', { someOption: 1 });

Returns any The return is defined by the command

stop

Stop the command

Parameters

  • id String Command ID
  • options Object Options (optional, default {})

Examples

javascript
commands.stop('myCommand', { someOption: 1 });

Returns any The return is defined by the command

isActive

Check if the command is active. You activate commands with run
and disable them with stop. If the command was created without stop
method it can't be registered as active

Parameters

Examples

javascript
const cId = 'some-command';
commands.run(cId);
commands.isActive(cId);
// -> true
commands.stop(cId);
commands.isActive(cId);
// -> false

Returns Boolean

getActive

Get all active commands

Examples

javascript
console.log(commands.getActive());
// -> { someCommand: itsLastReturn, anotherOne: ... };

Returns Object


File: docs/api/component.md

Component

The Component object represents a single node of our template structure, so when you update its properties the changes are
immediately reflected on the canvas and in the code to export (indeed, when you ask to export the code we just go through all
the tree of nodes).
An example on how to update properties:

js
component.set({
 tagName: 'span',
 attributes: { ... },
 removable: false,
});
component.get('tagName');
// -> 'span'

Properties

  • type String? Component type, eg. text, image, video, etc.
  • tagName String? HTML tag of the component, eg. span. Default: div
  • attributes Object? Key-value object of the component's attributes, eg. { title: 'Hello' } Default: {}
  • name String? Name of the component. Will be used, for example, in Layers and badges
  • removable Boolean? When true the component is removable from the canvas, default: true
  • draggable (Boolean | String | Function)? Indicates if it's possible to drag the component inside others.
    You can also specify a query string to identify elements,
    eg. '.some-class[title=Hello], [data-gjs-type=column]' means you can drag the component only inside elements
    containing some-class class and Hello title, and column components. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drag is possible. Default: true
  • droppable (Boolean | String | Function)? Indicates if it's possible to drop other components inside. You can use
    a query string as with draggable. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drop is possible. Default: true
  • badgable Boolean? Set to false if you don't want to see the badge (with the name) over the component. Default: true
  • stylable (Boolean | Array<String>)? True if it's possible to style the component.
    You can also indicate an array of CSS properties which is possible to style, eg. ['color', 'width'], all other properties
    will be hidden from the style manager. Default: true
  • stylable-require Array<String>? Indicate an array of style properties to show up which has been marked as toRequire. Default: []
  • unstylable Array<String>? Indicate an array of style properties which should be hidden from the style manager. Default: []
  • highlightable Boolean? It can be highlighted with 'dotted' borders if true. Default: true
  • copyable Boolean? True if it's possible to clone the component. Default: true
  • resizable Boolean? Indicates if it's possible to resize the component. It's also possible to pass an object as options for the Resizer. Default: false
  • editable Boolean? Allow to edit the content of the component (used on Text components). Default: false
  • layerable Boolean? Set to false if you need to hide the component inside Layers. Default: true
  • selectable Boolean? Allow component to be selected when clicked. Default: true
  • hoverable Boolean? Shows a highlight outline when hovering on the element if true. Default: true
  • locked Boolean? Disable the selection of the component and its children in the canvas. You can unlock a children by setting its locked property to false. Default: undefined
  • void Boolean? This property is used by the HTML exporter as void elements don't have closing tags, eg. ``, <hr/>, etc. Default: false
  • style Object? Component default style, eg. { width: '100px', height: '100px', 'background-color': 'red' }
  • styles String? Component related styles, eg. .my-component-class { color: red }
  • content String? Content of the component (not escaped) which will be appended before children rendering. Default: ''
  • icon String? Component's icon, this string will be inserted before the name (in Layers and badge), eg. it can be an HTML string ''. Default: ''
  • script (String | Function)? Component's javascript. More about it here. Default: ''
  • script-export (String | Function)? You can specify javascript available only in export functions (eg. when you get the HTML).
    If this property is defined it will overwrite the script one (in export functions). Default: ''
  • traits Array<(Object | String)>? Component's traits. More about it here. Default: ['id', 'title']
  • propagate Array<String>? Indicates an array of properties which will be inhereted by all NEW appended children.
    For example if you create a component likes this: { removable: false, draggable: false, propagate: ['removable', 'draggable'] }
    and append some new component inside, the new added component will get the exact same properties indicated in the propagate array (and the propagate property itself). Default: []
  • toolbar Array<Object>? Set an array of items to show up inside the toolbar when the component is selected (move, clone, delete).
    Eg. toolbar: [ { attributes: {class: 'fa fa-arrows'}, command: 'tlb-move' }, ... ].
    By default, when toolbar property is falsy the editor will add automatically commands core:component-exit (select parent component, added if there is one), tlb-move (added if draggable) , tlb-clone (added if copyable), tlb-delete (added if removable).
  • components Collection<Component>? Children components. Default: null
  • delegate Object? Delegate commands to other components. Available commands remove | move | copy | select. eg. { remove: (cmp) => cmp.closestType('other-type') }

init

Hook method, called once the model is created

updated

Hook method, called when the model has been updated (eg. updated some model's property)

Parameters

  • property String Property name, if triggered after some property update
  • value any Property value, if triggered after some property update
  • previous any Property previous value, if triggered after some property update

removed

Hook method, called once the model has been removed

is

Check component's type

Parameters

Examples

javascript
component.is('image')
// -> false

Returns Boolean

props

Return all the propeties

Returns Object

index

Get the index of the component in the parent collection.

Returns Number

setDragMode

Change the drag mode of the component.
To get more about this feature read: https://github.com/GrapesJS/grapesjs/issues/1936

Parameters

  • value String Drag mode, options: 'absolute' | 'translate' | ''

Returns this

getDragMode

Get the drag mode of the component.

Returns String Drag mode value, options: 'absolute' | 'translate' | ''

setSymbolOverride

Set symbol override.
By setting override to true, none of its property changes will be propagated to relative symbols.
By setting override to specific properties, changes of those properties will be skipped from propagation.

Parameters

Examples

javascript
component.setSymbolOverride(['children', 'classes']);

getSymbolOverride

Get symbol override value.

Returns (Boolean | Array<String>)

find

Find inner components by query string.
ATTENTION: this method works only with already rendered component

Parameters

Examples

javascript
component.find('div > .class');
// -> [Component, Component, ...]

Returns Array Array of components

findType

Find all inner components by component type.
The advantage of this method over find is that you can use it
also before rendering the component

Parameters

  • query (String | Function) Component type or matcher function
  • opts Object? Search options
  • opts.max Number? Maximum number of matches before exiting

Examples

javascript
const allImages = component.findType('image');
console.log(allImages[0]) // prints the first found component

const someComponents = component.findType((cmp) => cmp.getType() === 'something', { max: 2 });

Returns Array<Component>

findFirstType

Find the first inner component by component type.
If no component is found, it returns undefined.

Parameters

  • query (String | Function) Component type or matcher function

Examples

javascript
const image = component.findFirstType('image');
if (image) {
 console.log(image);
}

const firstImage = component.findFirstType((cmp) => cmp.is('image'));

Returns (Component | undefined)

closest

Find the closest parent component by query string.
ATTENTION: this method works only with already rendered component

Parameters

Examples

javascript
component.closest('div.some-class');
// -> Component

Returns Component

closestType

Find the closest parent component by its type.
The advantage of this method over closest is that you can use it
also before rendering the component

Parameters

  • query (String | Function) Component type or matcher function

Examples

javascript
const Section = component.closestType('section');
console.log(Section);

const namedSection = component.closestType((cmp) => cmp.getName() === 'Section');

Returns Component Found component, otherwise undefined

contains

The method returns a Boolean value indicating whether the passed
component is a descendant of a given component

Parameters

  • component Component Component to check

Returns Boolean

replaceWith

Replace a component with another one

Parameters

  • el (String | Component) Component or HTML string
  • opts Object Options for the append action (optional, default {})

Examples

javascript
const result = component.replaceWith('Some new content');
// result -> [Component]

Returns Array<Component> New replaced components

setAttributes

Update attributes of the component

Parameters

  • attrs Object Key value attributes
  • opts SetAttrOptions (optional, default {skipWatcherUpdates:false,fromDataSource:false})
  • options Object Options for the model update

Examples

javascript
component.setAttributes({ id: 'test', 'data-key': 'value' });

Returns this

addAttributes

Add attributes to the component

Parameters

  • attrs Object Key value attributes
  • opts SetAttrOptions (optional, default {})
  • options Object Options for the model update

Examples

javascript
component.addAttributes({ 'data-key': 'value' });

Returns this

removeAttributes

Remove attributes from the component

Parameters

  • attrs (String | Array<String>) Array of attributes to remove (optional, default [])
  • opts SetOptions (optional, default {})
  • options Object Options for the model update

Examples

javascript
component.removeAttributes('some-attr');
component.removeAttributes(['some-attr1', 'some-attr2']);

Returns this

getStyle

Get the style of the component

Parameters

  • opts GetComponentStyleOpts?

Returns Object

setStyle

Set the style on the component

Parameters

  • prop Object Key value style object (optional, default {})
  • opts UpdateStyleOptions (optional, default {})

Examples

javascript
component.setStyle({ color: 'red' });

Returns Object

getAttributes

Return all component's attributes

Parameters

Returns Object

addClass

Add classes

Parameters

Examples

javascript
model.addClass('class1');
model.addClass('class1 class2');
model.addClass(['class1', 'class2']);
// -> [SelectorObject, ...]

Returns Array Array of added selectors

setClass

Set classes (resets current collection)

Parameters

Examples

javascript
model.setClass('class1');
model.setClass('class1 class2');
model.setClass(['class1', 'class2']);
// -> [SelectorObject, ...]

Returns Array Array of added selectors

removeClass

Remove classes

Parameters

Examples

javascript
model.removeClass('class1');
model.removeClass('class1 class2');
model.removeClass(['class1', 'class2']);
// -> [SelectorObject, ...]

Returns Array Array of removed selectors

getClasses

Returns component's classes as an array of strings

Returns Array

append

Add new component children

Parameters

  • components (Component | String) Component to add
  • opts Object Options for the append action (optional, default {})

Examples

javascript
someComponent.get('components').length // -> 0
const videoComponent = someComponent.append('<video></video>')[0];
// This will add 2 components (`video` and `div`) to your `someComponent`
someComponent.get('components').length // -> 2
// You can pass components directly
otherComponent.append(otherComponent2);
otherComponent.append([otherComponent3, otherComponent4]);
// append at specific index (eg. at the beginning)
someComponent.append(otherComponent, { at: 0 });

Returns Array Array of appended components

components

Set new collection if components are provided, otherwise the
current collection is returned

Parameters

  • components (Component | Array<Component> | String)? Component Definitions or HTML string
  • opts Object Options, same as in Component.append() (optional, default {})

Examples

javascript
// Set new collection
component.components('');
// Get current collection
const collection = component.components();
console.log(collection.length);
// -> 2

Returns (Collection | Array<Component>)

getChildAt

If exists, returns the child component at specific index.

Parameters

  • index Number Index of the component to return

Examples

javascript
// Return first child
component.getChildAt(0);
// Return second child
component.getChildAt(1);

Returns (Component | null)

getLastChild

If exists, returns the last child component.

Examples

javascript
const lastChild = component.getLastChild();

Returns (Component | null)

empty

Remove all inner components

  • @return {this}

Parameters

  • opts (optional, default {})

parent

Get the parent component, if exists

Parameters

  • opts any (optional, default {})

Examples

javascript
component.parent();
// -> Component

Returns (Component | null)

parents

Return all parents of the component.

Returns Array<Component>

getTraits

Get traits.

Examples

javascript
const traits = component.getTraits();
console.log(traits);
// [Trait, Trait, Trait, ...]

Returns **Array**

setTraits

Replace current collection of traits with a new one.

Parameters

Examples

javascript
const traits = component.setTraits([{ type: 'checkbox', name: 'disabled'}, ...]);
console.log(traits);
// [Trait, ...]

Returns **Array**

getTrait

Get the trait by id/name.

Parameters

  • id String The id or name of the trait

Examples

javascript
const traitTitle = component.getTrait('title');
traitTitle && traitTitle.set('label', 'New label');

Returns (Trait | null) Trait getModelToStyle

updateTrait

Update a trait.

Parameters

  • id String The id or name of the trait
  • props Object Object with the props to update

Examples

javascript
component.updateTrait('title', {
 type: 'select',
 options: [ 'Option 1', 'Option 2' ],
});

Returns this

getTraitIndex

Get the trait position index by id/name. Useful in case you want to
replace some trait, at runtime, with something else.

Parameters

  • id String The id or name of the trait

Examples

javascript
const traitTitle = component.getTraitIndex('title');
console.log(traitTitle); // 1

Returns Number Index position of the current trait

removeTrait

Remove trait/s by id/s.

Parameters

Examples

javascript
component.removeTrait('title');
component.removeTrait(['title', 'id']);

Returns **Array** Array of removed traits

addTrait

Add new trait/s.

Parameters

  • trait (String | Object | Array<(String | Object)>) Trait to add (or an array of traits)
  • opts Options Options for the add (optional, default {})

Examples

javascript
component.addTrait('title', { at: 1 }); // Add title trait (`at` option is the position index)
component.addTrait({
 type: 'checkbox',
 name: 'disabled',
});
component.addTrait(['title', {...}, ...]);

Returns **Array** Array of added traits

getName

Get the name of the component.

Parameters

  • opts Object Options (optional, default {})

    • opts.noCustom Boolean? Avoid custom name assigned to the component.

Returns String

setName

Update component name.

Parameters

  • name String New name.
  • opts SetOptions (optional, default {})

getIcon

Get the icon string

Returns String

toHTML

Return HTML string of the component

Parameters

  • opts Object Options (optional, default {})

    • opts.tag String? Custom tagName
    • opts.attributes (Object | Function) You can pass an object of custom attributes to replace with the current ones or you can even pass a function to generate attributes dynamically. (optional, default null)
    • opts.withProps Boolean? Include component properties as data-gjs-* attributes. This allows you to have re-importable HTML.
    • opts.altQuoteAttr Boolean? In case the attribute value contains a " char, instead of escaping it (attr="value &quot;"), the attribute will be quoted using single quotes (attr='value "').

Examples

javascript
// Simple HTML return
component.set({ tagName: 'span' });
component.setAttributes({ title: 'Hello' });
component.toHTML();
// -> 

// Custom attributes
component.toHTML({ attributes: { 'data-test': 'Hello' } });
// -> 

// Custom dynamic attributes
component.toHTML({
 attributes(component, attributes) {
   if (component.get('tagName') == 'span') {
     attributes.title = 'Custom attribute';
   }
   return attributes;
 },
});
// ->

Returns String HTML string

getInnerHTML

Get inner HTML of the component

Parameters

  • opts Object Same options of toHTML (optional, default {})

Returns String HTML string

getChangedProps

Return an object containing only changed props

Parameters

  • res Partial<ComponentDefinition>

Returns Partial<ComponentDefinition>

getId

Return the component id

Returns String

setId

Set new id on the component

Parameters

Returns this

getEl

Get the DOM element of the component.
This works only if the component is already rendered

Parameters

  • frame Frame Specific frame from which taking the element

Returns HTMLElement

getView

Get the View of the component.
This works only if the component is already rendered

Parameters

  • frame Frame Get View of a specific frame

Returns ComponentView

onAll

Execute callback function on itself and all inner components

Parameters

  • clb Function Callback function, the model is passed as an argument

Examples

javascript
component.onAll(component => {
 // do something with component
})

Returns this

forEachChild

Execute a callback function on all inner child components.

Parameters

  • clb Function Callback function, the child component is passed as an argument

Examples

javascript
component.forEachChild(child => {
 console.log(child)
})

remove

Remove the component

Parameters

  • opts any (optional, default {})

Returns this

move

Move the component to another destination component

Parameters

  • component Component Destination component (so the current one will be appended as a child)
  • opts Object Options for the append action (optional, default {})

Examples

javascript
// Move the selected component on top of the wrapper
const dest = editor.getWrapper();
editor.getSelected().move(dest, { at: 0 });

Returns this

isInstanceOf

Check if the component is an instance of some component type.

Parameters

Examples

javascript
// Add a new component type by extending an existing one
editor.Components.addType('text-ext', { extend: 'text' });
// Append a new component somewhere
const newTextExt = editor.getSelected().append({ type: 'text-ext' })[0];
newTextExt.isInstanceOf('text-ext'); // true
newTextExt.isInstanceOf('text'); // true

Returns Boolean

isChildOf

Check if the component is a child of some other component (or component type)

Parameters

  • component (Component | String) Component parent to check. In case a string is passed,
    the check will be performed on the component type.

Examples

javascript
const newTextComponent = editor.getSelected().append({
 type: 'text',
 components: 'My text **here**',
})[0];
const innerComponent = newTextComponent.find('b')[0];
innerComponent.isChildOf(newTextComponent); // true
innerComponent.isChildOf('text'); // true

Returns Boolean


File: docs/api/components.md

Components

With this module is possible to manage components inside the canvas. You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object

js
const editor = grapesjs.init({
 domComponents: {
   // options
 }
})

Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.

js
// Listen to events
editor.on('component:create', () => { ... });

// Use the API
const cmp = editor.Components;
cmp.addType(...);

Available Events

  • component:create - Component is created (only the model, is not yet mounted in the canvas), called after the init() method
  • component:mount - Component is mounted to an element and rendered in canvas
  • component:add - Triggered when a new component is added to the editor, the model is passed as an argument to the callback
  • component:remove - Triggered when a component is removed, the model is passed as an argument to the callback
  • component:remove:before - Triggered before the remove of the component, the model, remove function (if aborted via options, with this function you can complete the remove) and options (use options.abort = true to prevent remove), are passed as arguments to the callback
  • component:clone - Triggered when a component is cloned, the new model is passed as an argument to the callback
  • component:update - Triggered when a component is updated (moved, styled, etc.), the model is passed as an argument to the callback
  • component:update:{propertyName} - Listen any property change, the model is passed as an argument to the callback
  • component:styleUpdate - Triggered when the style of the component is updated, the model is passed as an argument to the callback
  • component:styleUpdate:{propertyName} - Listen for a specific style property change, the model is passed as an argument to the callback
  • component:selected - New component selected, the selected model is passed as an argument to the callback
  • component:deselected - Component deselected, the deselected model is passed as an argument to the callback
  • component:toggled - Component selection changed, toggled model is passed as an argument to the callback
  • component:type:add - New component type added, the new type is passed as an argument to the callback
  • component:type:update - Component type updated, the updated type is passed as an argument to the callback
  • component:drag:start - Component drag started. Passed an object, to the callback, containing the target (component to drag), parent (parent of the component) and index (component index in the parent)
  • component:drag - During component drag. Passed the same object as in component:drag:start event, but in this case, parent and index are updated by the current pointer
  • component:drag:end - Component drag ended. Passed the same object as in component:drag:start event, but in this case, parent and index are updated by the final pointer
  • component:resize - During component resize.

Methods

getWrapper

Returns root component inside the canvas. Something like `` inside HTML page
The wrapper doesn't differ from the original Component Model

Examples

javascript
// Change background of the wrapper and set some attribute
var wrapper = cmp.getWrapper();
wrapper.set('style', {'background-color': 'red'});
wrapper.set('attributes', {'title': 'Hello!'});

Returns Component Root Component

getComponents

Returns wrapper's children collection. Once you have the collection you can
add other Components(Models) inside. Each component can have several nested
components inside and you can nest them as more as you wish.

Examples

javascript
// Let's add some component
var wrapperChildren = cmp.getComponents();
var comp1 = wrapperChildren.add({
  style: { 'background-color': 'red'}
});
var comp2 = wrapperChildren.add({
  tagName: 'span',
  attributes: { title: 'Hello!'}
});
// Now let's add an other one inside first component
// First we have to get the collection inside. Each
// component has 'components' property
var comp1Children = comp1.get('components');
// Procede as before. You could also add multiple objects
comp1Children.add([
  { style: { 'background-color': 'blue'}},
  { style: { height: '100px', width: '100px'}}
]);
// Remove comp2
wrapperChildren.remove(comp2);

Returns Components Collection of components

addComponent

Add new components to the wrapper's children. It's the same
as 'cmp.getComponents().add(...)'

Parameters

  • component (Object | Component | Array<Object>) Component/s to add

    • component.tagName string Tag name (optional, default 'div')
    • component.type string Type of the component. Available: ''(default), 'text', 'image' (optional, default '')
    • component.removable boolean If component is removable (optional, default true)
    • component.draggable boolean If is possible to move the component around the structure (optional, default true)
    • component.droppable boolean If is possible to drop inside other components (optional, default true)
    • component.badgable boolean If the badge is visible when the component is selected (optional, default true)
    • component.stylable boolean If is possible to style component (optional, default true)
    • component.copyable boolean If is possible to copy&paste the component (optional, default true)
    • component.content string String inside component (optional, default '')
    • component.style Object Style object (optional, default {})
    • component.attributes Object Attribute object (optional, default {})
  • opt Object the options object to be used by the [Components.add]getComponents method (optional, default {})

Examples

javascript
// Example of a new component with some extra property
var comp1 = cmp.addComponent({
  tagName: 'div',
  removable: true, // Can't remove it
  draggable: true, // Can't move it
  copyable: true, // Disable copy/past
  content: 'Content text', // Text inside component
  style: { color: 'red'},
  attributes: { title: 'here' }
});

Returns (Component | Array<Component>) Component/s added

clear

Remove all components

Parameters

  • opts (optional, default {})

Returns this

addType

Add new component type.
Read more about this in Define New Component

Parameters

Returns this

getType

Get component type.
Read more about this in Define New Component

Parameters

Returns Object Component type definition, eg. { model: ..., view: ... }

removeType

Remove component type

Parameters

Returns (Object | undefined) Removed component type, undefined otherwise

getTypes

Return the array of all types

Returns Array

isComponent

Check if the object is a [Component].

Parameters

Examples

javascript
cmp.isComponent(editor.getSelected()); // true
cmp.isComponent({}); // false

Returns Boolean

addSymbol

Add a new symbol from a component.
If the passed component is not a symbol, it will be converted to an instance and will return the main symbol.
If the passed component is already an instance, a new instance will be created and returned.
If the passed component is the main symbol, a new instance will be created and returned.

Parameters

  • component Component Component from which create a symbol.

Examples

javascript
const symbol = cmp.addSymbol(editor.getSelected());
// cmp.getSymbolInfo(symbol).isSymbol === true;

Returns Component

getSymbols

Get the array of main symbols.

Examples

javascript
const symbols = cmp.getSymbols();
// [Component, Component, ...]
// Removing the main symbol will detach all the relative instances.
symbols[0].remove();

Returns Array<Component>

detachSymbol

Detach symbol instance from the main one.
The passed symbol instance will become a regular component.

Parameters

  • component Component The component symbol to detach.

Examples

javascript
const cmpInstance = editor.getSelected();
// cmp.getSymbolInfo(cmpInstance).isInstance === true;
cmp.detachSymbol(cmpInstance);
// cmp.getSymbolInfo(cmpInstance).isInstance === false;

getSymbolInfo

Get info about the symbol.

Parameters

  • component Component Component symbol from which to get the info.
  • opts {withChanges: string?} (optional, default {})

Examples

javascript
cmp.getSymbolInfo(editor.getSelected());
// > { isSymbol: true, isMain: false, isInstance: true, ... }

Returns Object Object containing symbol info.

canMove

Check if a component can be moved inside another one.

Parameters

  • target Component The target component is the one that is supposed to receive the source one.
  • source (Component | String) The source can be another component, a component definition or an HTML string.
  • index Number? Index position, if not specified, the check will be performed against appending the source to the target.

Examples

javascript
const rootComponent = editor.getWrapper();
const someComponent = editor.getSelected();

// Check with two components
editor.Components.canMove(rootComponent, someComponent);

// Check with component definition
editor.Components.canMove(rootComponent, { tagName: 'a', draggable: false });

// Check with HTML string
editor.Components.canMove(rootComponent, '<form>...</form>');

Returns Object Object containing the result (Boolean), source, target (as Components), and a reason (Number) with these meanings:* 0 - Invalid source. This is a default value and should be ignored in case the result is true.

  • 1 - Source doesn't accept target as destination.
  • 2 - Target doesn't accept source.