## Component
**Extends Model.extend(Styleable)**
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'
```
[Component]: component.html
### Properties
* `type` **[String][1]?** Component type, eg. `text`, `image`, `video`, etc.
* `tagName` **[String][1]?** HTML tag of the component, eg. `span`. Default: `div`
* `attributes` **[Object][2]?** Key-value object of the component's attributes, eg. `{ title: 'Hello' }` Default: `{}`
* `name` **[String][1]?** Name of the component. Will be used, for example, in Layers and badges
* `removable` **[Boolean][3]?** When `true` the component is removable from the canvas, default: `true`
* `draggable` **([Boolean][3] | [String][1] | [Function][4])?** 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. 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][3] | [String][1] | [Function][4])?** 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][3]?** Set to false if you don't want to see the badge (with the name) over the component. Default: `true`
* `stylable` **([Boolean][3] | [Array][5]<[String][1]>)?** 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][5]<[String][1]>?** Indicate an array of style properties to show up which has been marked as `toRequire`. Default: `[]`
* `unstylable` **[Array][5]<[String][1]>?** Indicate an array of style properties which should be hidden from the style manager. Default: `[]`
* `highlightable` **[Boolean][3]?** It can be highlighted with 'dotted' borders if true. Default: `true`
* `copyable` **[Boolean][3]?** True if it's possible to clone the component. Default: `true`
* `resizable` **[Boolean][3]?** Indicates if it's possible to resize the component. It's also possible to pass an object as [options for the Resizer][6]. Default: `false`
* `editable` **[Boolean][3]?** Allow to edit the content of the component (used on Text components). Default: `false`
* `layerable` **[Boolean][3]?** Set to `false` if you need to hide the component inside Layers. Default: `true`
* `selectable` **[Boolean][3]?** Allow component to be selected when clicked. Default: `true`
* `hoverable` **[Boolean][3]?** Shows a highlight outline when hovering on the element if `true`. Default: `true`
* `void` **[Boolean][3]?** This property is used by the HTML exporter as void elements don't have closing tags, eg. `
`, `
`, etc. Default: `false`
* `style` **[Object][2]?** Component default style, eg. `{ width: '100px', height: '100px', 'background-color': 'red' }`
* `styles` **[String][1]?** Component related styles, eg. `.my-component-class { color: red }`
* `content` **[String][1]?** Content of the component (not escaped) which will be appended before children rendering. Default: `''`
* `icon` **[String][1]?** 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][1] | [Function][4])?** Component's javascript. More about it [here][7]. Default: `''`
* `script-export` **([String][1] | [Function][4])?** 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][5]<([Object][2] | [String][1])>?** Component's traits. More about it [here][8]. Default: `['id', 'title']`
* `propagate` **[Array][5]<[String][1]>?** 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][5]<[Object][2]>?** 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][9]>?** 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][1]** 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][1]** Component type
#### Examples
```javascript
component.is('image')
// -> false
```
Returns **[Boolean][3]**
### props
Return all the propeties
Returns **[Object][2]**
### index
Get the index of the component in the parent collection.
Returns **[Number][10]**
### setDragMode
Change the drag mode of the component.
To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][11]
#### Parameters
* `value` **[String][1]** 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][1]** Query string
#### Examples
```javascript
component.find('div > .class');
// -> [Component, Component, ...]
```
Returns **[Array][5]** 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][1]** Component type
#### Examples
```javascript
const allImages = component.findType('image');
console.log(allImages[0]) // prints the first found component
```
Returns **[Array][5]<[Component][9]>**
### closest
Find the closest parent component by query string.
**ATTENTION**: this method works only with already rendered component
#### Parameters
* `query` **[string][1]** Query string
#### Examples
```javascript
component.closest('div.some-class');
// -> Component
```
Returns **[Component][9]**
### 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][1]** Component type
#### Examples
```javascript
const Section = component.closestType('section');
console.log(Section);
```
Returns **[Component][9]** 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][9]** Component to check
Returns **[Boolean][3]**
### replaceWith
Replace a component with another one
#### Parameters
* `el` **([String][1] | [Component][9])** Component or HTML string
#### Examples
```javascript
component.replaceWith('Some new content
');
// -> Component
```
Returns **([Component][9] | [Array][5]<[Component][9]>)** New added component/s
### setAttributes
Update attributes of the component
#### Parameters
* `attrs` **[Object][2]** Key value attributes
* `opts` (optional, default `{}`)
* `options` **[Object][2]** 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][2]** Key value attributes
* `opts` (optional, default `{}`)
* `options` **[Object][2]** Options for the model update
#### Examples
```javascript
component.addAttributes({ 'data-key': 'value' });
```
Returns **this**
### removeAttributes
Remove attributes from the component
#### Parameters
* `attrs` **([String][1] | [Array][5]<[String][1]>)** Array of attributes to remove (optional, default `[]`)
* `opts` (optional, default `{}`)
* `options` **[Object][2]** 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
* `options` (optional, default `{}`)
* `optsAdd` (optional, default `{}`)
Returns **[Object][2]**
### setStyle
Set the style on the component
#### Parameters
* `prop` **[Object][2]** Key value style object (optional, default `{}`)
* `opts` (optional, default `{}`)
#### Examples
```javascript
component.setStyle({ color: 'red' });
```
Returns **[Object][2]**
### getAttributes
Return all component's attributes
#### Parameters
* `opts` (optional, default `{}`)
Returns **[Object][2]**
### addClass
Add classes
#### Parameters
* `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes
#### Examples
```javascript
model.addClass('class1');
model.addClass('class1 class2');
model.addClass(['class1', 'class2']);
// -> [SelectorObject, ...]
```
Returns **[Array][5]** Array of added selectors
### setClass
Set classes (resets current collection)
#### Parameters
* `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes
#### Examples
```javascript
model.setClass('class1');
model.setClass('class1 class2');
model.setClass(['class1', 'class2']);
// -> [SelectorObject, ...]
```
Returns **[Array][5]** Array of added selectors
### removeClass
Remove classes
#### Parameters
* `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes
#### Examples
```javascript
model.removeClass('class1');
model.removeClass('class1 class2');
model.removeClass(['class1', 'class2']);
// -> [SelectorObject, ...]
```
Returns **[Array][5]** Array of removed selectors
### getClasses
Returns component's classes as an array of strings
Returns **[Array][5]**
### append
Add new component children
#### Parameters
* `components` **([Component][9] | [String][1])** Component to add
* `opts` **[Object][2]** Options for the append action (optional, default `{}`)
#### Examples
```javascript
someComponent.get('components').length // -> 0
const videoComponent = someComponent.append('')[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][5]** Array of appended components
### components
Set new collection if `components` are provided, otherwise the
current collection is returned
#### Parameters
* `components` **([Component][9] | [String][1])?** Component Definitions or HTML string
* `opts` **[Object][2]** 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][5]<[[Component][9]]>)**
### getChildAt
If exists, returns the child component at specific index.
#### Parameters
* `index` **[Number][10]** Index of the component to return
#### Examples
```javascript
// Return first child
component.getChildAt(0);
// Return second child
component.getChildAt(1);
```
Returns **([[Component][9]] | null)**
### getLastChild
If exists, returns the last child component.
#### Examples
```javascript
const lastChild = component.getLastChild();
```
Returns **([[Component][9]] | null)**
### empty
Remove all inner components
* @return {this}
#### Parameters
* `opts` (optional, default `{}`)
### parent
Get the parent component, if exists
#### Parameters
* `opts` (optional, default `{}`)
#### Examples
```javascript
component.parent();
// -> Component
```
Returns **([Component][9] | null)**
### getTraits
Get traits.
#### Examples
```javascript
const traits = component.getTraits();
console.log(traits);
// [Trait, Trait, Trait, ...]
```
Returns **[Array][5]\**
### setTraits
Replace current collection of traits with a new one.
#### Parameters
* `traits` **[Array][5]<[Object][2]>** Array of trait definitions
#### Examples
```javascript
const traits = component.setTraits([{ type: 'checkbox', name: 'disabled'}, ...]);
console.log(traits);
// [Trait, ...]
```
Returns **[Array][5]\**
### getTrait
Get the trait by id/name.
#### Parameters
* `id` **[String][1]** 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][1]** The `id` or `name` of the trait
* `props` **[Object][2]** 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][1]** The `id` or `name` of the trait
#### Examples
```javascript
const traitTitle = component.getTraitIndex('title');
console.log(traitTitle); // 1
```
Returns **[Number][10]** Index position of the current trait
### removeTrait
Remove trait/s by id/s.
#### Parameters
* `id` **([String][1] | [Array][5]<[String][1]>)** The `id`/`name` of the trait (or an array)
#### Examples
```javascript
component.removeTrait('title');
component.removeTrait(['title', 'id']);
```
Returns **[Array][5]\** Array of removed traits
### addTrait
Add new trait/s.
#### Parameters
* `trait` **([String][1] | [Object][2] | [Array][5]<([String][1] | [Object][2])>)** 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][5]\** Array of added traits
### getName
Get the name of the component
Returns **[String][1]**
### getIcon
Get the icon string
Returns **[String][1]**
### toHTML
Return HTML string of the component
#### Parameters
* `opts` **[Object][2]** Options (optional, default `{}`)
* `opts.tag` **[String][1]?** Custom tagName
* `opts.attributes` **([Object][2] | [Function][4])** 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][3]?** Include component properties as `data-gjs-*` attributes. This allows you to have re-importable HTML.
* `opts.altQuoteAttr` **[Boolean][3]?** In case the attribute value contains a `"` char, instead of escaping it (`attr="value ""`), 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][1]** HTML string
### getInnerHTML
Get inner HTML of the component
#### Parameters
* `opts` **[Object][2]** Same options of `toHTML` (optional, default `{}`)
Returns **[String][1]** HTML string
### getChangedProps
Return an object containing only changed props
#### Parameters
* `res`
### getId
Return the component id
Returns **[String][1]**
### setId
Set new id on the component
#### Parameters
* `id` **[String][1]**
* `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][12]**
### 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][4]** Callback function, the model is passed as an argument
#### Examples
```javascript
component.onAll(component => {
// do something with component
})
```
Returns **this**
### remove
Remove the component
#### Parameters
* `opts` (optional, default `{}`)
Returns **this**
### move
Move the component to another destination component
#### Parameters
* `component` **[Component][9]** Destination component (so the current one will be appended as a child)
* `opts` **[Object][2]** 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
* `type` **[String][1]** Component type
#### 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][3]**
### isChildOf
Check if the component is a child of some other component (or component type)
#### Parameters
* `component` **([[Component][9]] | [String][1])** 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][3]**
[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[6]: https://github.com/artf/grapesjs/blob/master/src/utils/Resizer.js
[7]: /modules/Components-js.html
[8]: /modules/Traits.html
[9]: #component
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
[11]: https://github.com/artf/grapesjs/issues/1936
[12]: https://developer.mozilla.org/docs/Web/HTML/Element