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

# 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 (opens new window) 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

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

Returns Boolean (opens new window)

# props

Return all the propeties

Returns Object (opens new window)

# index

Get the index of the component in the parent collection.

Returns Number (opens new window)

# setDragMode

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

# Parameters

Returns this

# getDragMode

Get the drag mode of the component.

Returns String (opens new window) 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

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

# getSymbolOverride

Get symbol override value.

Returns (Boolean (opens new window) | Array (opens new window)<String (opens new window)>)

# find

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

# Parameters

# Examples

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

Returns Array (opens new window) 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

# Examples

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

Returns Array (opens new window)<Component>

# findFirstType

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

# Parameters

# Examples

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

Returns (Component | undefined (opens new window))

# closest

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

# Parameters

# 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

# Examples

const Section = component.closestType('section');
console.log(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 (opens new window)

# replaceWith

Replace a component with another one

# Parameters

# Examples

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

Returns Array (opens new window)<Component> New replaced components

# setAttributes

Update attributes of the component

# Parameters

# Examples

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

Returns this

# addAttributes

Add attributes to the component

# Parameters

# Examples

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

Returns this

# removeAttributes

Remove attributes from the component

# Parameters

# Examples

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

Returns this

# getStyle

Get the style of the component

# Parameters

  • options any (optional, default {})
  • optsAdd any (optional, default {})

Returns Object (opens new window)

# setStyle

Set the style on the component

# Parameters

# Examples

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

Returns Object (opens new window)

# getAttributes

Return all component's attributes

# Parameters

Returns Object (opens new window)

# addClass

Add classes

# Parameters

# Examples

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

Returns Array (opens new window) Array of added selectors

# setClass

Set classes (resets current collection)

# Parameters

# Examples

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

Returns Array (opens new window) Array of added selectors

# removeClass

Remove classes

# Parameters

# Examples

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

Returns Array (opens new window) Array of removed selectors

# getClasses

Returns component's classes as an array of strings

Returns Array (opens new window)

# append

Add new component children

# Parameters

# 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]);
// append at specific index (eg. at the beginning)
someComponent.append(otherComponent, { at: 0 });

Returns Array (opens new window) Array of appended components

# components

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

# Parameters

# 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 (opens new window)<Component>)

# getChildAt

If exists, returns the child component at specific index.

# Parameters

# Examples

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

Returns (Component | null)

# getLastChild

If exists, returns the last child component.

# Examples

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

component.parent();
// -> Component

Returns (Component | null)

# parents

Return all parents of the component.

Returns Array (opens new window)<Component>

# getTraits

Get traits.

# Examples

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

Returns Array (opens new window)<Trait>

# setTraits

Replace current collection of traits with a new one.

# Parameters

# Examples

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

Returns Array (opens new window)<Trait>

# getTrait

Get the trait by id/name.

# Parameters

# Examples

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

Returns (Trait | null) Trait getModelToStyle

# updateTrait

Update a trait.

# Parameters

# 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

# Examples

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

Returns Number (opens new window) Index position of the current trait

# removeTrait

Remove trait/s by id/s.

# Parameters

# Examples

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

Returns Array (opens new window)<Trait> Array of removed traits

# addTrait

Add new trait/s.

# Parameters

# 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 (opens new window)<Trait> Array of added traits

# getName

Get the name of the component.

# Parameters

Returns String (opens new window)

# setName

Update component name.

# Parameters

# getIcon

Get the icon string

Returns String (opens new window)

# toHTML

Return HTML string of the component

# Parameters

# 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 (opens new window) HTML string

# getInnerHTML

Get inner HTML of the component

# Parameters

Returns String (opens new window) HTML string

# getChangedProps

Return an object containing only changed props

# Parameters

  • res Partial<ComponentDefinition>

Returns Partial<ComponentDefinition>

# getId

Return the component id

Returns String (opens new window)

# 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 (opens new window)

# 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

# Examples

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

Returns this

# forEachChild

Execute a callback function on all inner child components.

# Parameters

# Examples

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 (opens new window) Options for the append action (optional, default {})

# Examples

// 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

// 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 (opens new window)

# isChildOf

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

# Parameters

# Examples

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

Returns Boolean (opens new window)

← Panels →