## Canvas
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({
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` - When something is dragged inside the canvas, `DataTransfer` instance passed as an argument
* `canvas:dragover` - When something is dragging on canvas, `DataTransfer` instance passed as an argument
* `canvas:drop` - Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments
* `canvas:dragend` - When a drag operation is ended, `DataTransfer` instance 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
## Methods
* [getConfig][2]
* [getElement][3]
* [getFrameEl][4]
* [getWindow][5]
* [getDocument][6]
* [getBody][7]
* [setCustomBadgeLabel][8]
* [hasFocus][9]
* [scrollTo][10]
* [setZoom][11]
* [getZoom][12]
* [getCoords][13]
* [setCoords][14]
[Component]: component.html
[Frame]: frame.html
## getConfig
Get the configuration object
### Examples
```javascript
console.log(canvas.getConfig())
```
Returns **[Object][15]** Configuration object
## getElement
Get the canvas element
Returns **[HTMLElement][16]**
## getFrameEl
Get the main frame element of the canvas
Returns **[HTMLIFrameElement][17]**
## getWindow
Get the main frame window instance
Returns **[Window][18]**
## getDocument
Get the main frame document element
Returns **HTMLDocument**
## getBody
Get the main frame body element
Returns **[HTMLBodyElement][19]**
## setCustomBadgeLabel
Set custom badge naming strategy
### Parameters
* `f` **[Function][20]**
### Examples
```javascript
canvas.setCustomBadgeLabel(function(component){
return component.getName();
});
```
## getRect
Get canvas rectangular data
Returns **[Object][15]**
## hasFocus
Check if the canvas is focused
Returns **[Boolean][21]**
## 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][16] | [Component])**
* `opts` **[Object][15]** Options, same as options for `scrollIntoView` (optional, default `{}`)
* `opts.force` **[Boolean][21]** 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 alredy visible
canvas.scrollTo(selected, { force: true });
```
## setZoom
Set canvas zoom value
### Parameters
* `value` **[Number][22]** The zoom value, from 0 to 100
### 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][22]**
## setCoords
Set canvas position coordinates
### Parameters
* `x` **[Number][22]** Horizontal position
* `y` **[Number][22]** Vertical position
### 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][15]** Object containing coordinates
## addFrame
Add new frame to the canvas
### Parameters
* `props` **[Object][15]** Frame properties (optional, default `{}`)
* `opts` (optional, default `{}`)
### Examples
```javascript
canvas.addFrame({
name: 'Mobile home page',
x: 100, // Position in canvas
y: 100,
width: 500, // Frame dimensions
height: 600,
// device: 'DEVICE-ID',
components: [
'Title frame
',
'Paragraph frame
',
],
styles: `
.testh { color: red; }
.testp { color: blue; }
`,
});
```
Returns **[Frame]**
[1]: https://github.com/artf/grapesjs/blob/master/src/canvas/config/config.js
[2]: #getconfig
[3]: #getelement
[4]: #getframeel
[5]: #getwindow
[6]: #getdocument
[7]: #getbody
[8]: #setcustombadgelabel
[9]: #hasfocus
[10]: #scrollto
[11]: #setzoom
[12]: #getzoom
[13]: #getcoords
[14]: #setcoords
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[16]: https://developer.mozilla.org/docs/Web/HTML/Element
[17]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement
[18]: https://developer.mozilla.org/docs/Web/API/Window
[19]: https://developer.mozilla.org/docs/Web/HTML/Element/body
[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number