## Blocks
You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][1]
```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 }) => { ... });
```
* `block:custom` Event to use in case of [custom Block Manager UI](https\://grapesjs.com/docs/modules/Blocks.html#customization).
```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, ... }) => { ... });
```
[Block]: block.html
[Component]: component.html
## getConfig
Get configuration object
Returns **[Object][2]**
## add
Add new block.
### Parameters
* `id` **[String][3]** Block ID
* `props` **[Block]** Block properties
* `opts` (optional, default `{}`)
### Examples
```javascript
blockManager.add('h1-block', {
label: 'Heading',
content: 'Put your title here
',
category: 'Basic',
attributes: {
title: 'Insert h1 block'
}
});
```
Returns **[Block]** Added block
## get
Get the block by id.
### Parameters
* `id` **[String][3]** Block id
### Examples
```javascript
const block = blockManager.get('h1-block');
console.log(JSON.stringify(block));
// {label: 'Heading', content: 'Put your ...', ...}
```
Returns **[Block]**
## getAll
Return all blocks.
### Examples
```javascript
const blocks = blockManager.getAll();
console.log(JSON.stringify(blocks));
// [{label: 'Heading', content: 'Put your ...'}, ...]
```
Returns **Collection<[Block]>**
## getAllVisible
Return the visible collection, which containes blocks actually rendered
Returns **Collection<[Block]>**
## remove
Remove block.
### Parameters
* `block` **([String][3] | [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][4] | Collection)**
## getContainer
Return the Blocks container element
Returns **[HTMLElement][5]**
## getDragBlock
Returns currently dragging block.
Updated when the drag starts and cleared once it's done.
Returns **([Block] | [undefined][6])**
## getBlocksByCategory
Get blocks by category.
### Parameters
* `blocks` **[Array][4]\?**
### 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][4]\**
## render
Render blocks
### Parameters
* `blocks` **[Array][4]** Blocks to render, without the argument will render all global blocks
* `opts` **[Object][2]** Options (optional, default `{}`)
* `opts.external` **[Boolean][7]?** Render blocks in a new container (HTMLElement will be returned)
* `opts.ignoreCategories` **[Boolean][7]?** 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][5]** Rendered element
[1]: https://github.com/GrapesJS/grapesjs/blob/master/src/block_manager/config/config.ts
[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[5]: https://developer.mozilla.org/docs/Web/HTML/Element
[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean