GrapesJS

# 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:

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)? Indicates if it's possible to drag the component inside others. You can also specify a query string to indentify 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. Default: true
droppable (Boolean | String)? Indicates if it's possible to drop other components inside. You can use a query string as with draggable. 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: []
style-signature Array<String>? This option comes handy when you need to remove or export strictly component-specific rules. Be default, if this option is not empty, the editor will remove rules when there are no components, of that type, in the canvas. Eg. '['.navbar', '[navbar-']'. 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
void Boolean? This property is used by the HTML exporter as void elements don't have closing tags, eg. <br/>, <hr/>, etc. Default: false
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 like move, delete, etc. based on its properties.
components Collection<Component>? Children components. Default: null

# 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

type string Component type

# Examples

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/artf/grapesjs/issues/1936

# Parameters

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

Returns this

# find

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

# Parameters

query String Query string

# Examples

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

type String Component type

# Examples

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

Returns Array<Component>

# closest

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

# Parameters

query string Query string

# Examples

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

type String Component type

# Examples

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

Returns Component Found component, otherwise undefined

# replaceWith

Replace a component with another one

# Parameters

el (String | Component) Component or HTML string

# Examples

component.replaceWith('<div>Some new content</div>');
// -> Component

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

# setAttributes

Update attributes of the component

# Parameters

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

# Examples

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

Returns this

# addAttributes

Add attributes to the component

# Parameters

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

# Examples

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

Returns this

# getStyle

Get the style of the component

Returns Object

# setStyle

Set the style on the component

# Parameters

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

# Examples

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

Returns Object

# getAttributes

Return all component's attributes

Returns Object

# addClass

Add classes

# Parameters

classes (Array<String> | String) Array or string of classes

# Examples

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

classes (Array<String> | String) Array or string of classes

# Examples

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

Returns Array Array of added selectors

# removeClass

Remove classes

# Parameters

classes (Array<String> | String) Array or string of classes

# Examples

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, same as in model.add()(from backbone) (optional, default {})

# Examples

someComponent.get('components').length // -> 0
const videoComponent = someComponent.append('<video></video><div></div>')[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]);

Returns Array Array of appended components

# components

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

# Parameters

components (Component | String)? Components to set

# Examples

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

Returns (Collection | Array<Component>)

# empty

Remove all inner components

@return {this}

# Parameters

opts (optional, default {})

# parent

Get the parent component, if exists

# Examples

component.parent();
// -> Component

Returns Component

# getTrait

Get the trait by id/name

# Parameters

id String The id or name of the trait

# Examples

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

Returns Trait Trait model

# updateTrait

Update a trait

# Parameters

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

# Examples

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

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

id (String | Array<String>) The id/name of the trait (or an array)

# Examples

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

Returns Array Array of removed traits

# addTrait

Add trait/s by id/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

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

Returns String

# 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 one or you can even pass a function to generate attributes dynamically (optional, default null)

# Examples

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

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

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

Returns String HTML string

# getId

Return the component id

Returns String

# setId

Set new id on the component

# Parameters

id String
opts

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

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

Returns this

# remove

Remove the component

Returns this

# getList

The list of components is taken from the Components module. Initially, the list, was set statically on the Component object but it was not ok, as it was shared between multiple editor instances

# Parameters

model

# checkId

This method checks, for each parsed component and style object (are not Components/CSSRules yet), for duplicated id and fixes them This method is used in Components.js just after the parsing

# Parameters

components
styles (optional, default [])
list (optional, default {})

← DOM Components Panels →