## SelectorManager Selectors in GrapesJS are used in CSS Composer inside Rules and in Components as classes. To illustrate this concept let's take a look at this code: ```css span > #send-btn.btn{ ... } ``` ```html ``` In this scenario we get: * span -> selector of type `tag` * send-btn -> selector of type `id` * btn -> selector of type `class` So, for example, being `btn` the same class entity it'll be easier to refactor and track things. 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({ selectorManager: { // 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('selector:add', (selector) => { ... }); // Use the API const sm = editor.Selectors; sm.add(...); ``` ## Available Events * `selector:add` - Selector added. The [Selector] is passed as an argument to the callback. * `selector:remove` - Selector removed. The [Selector] is passed as an argument to the callback. * `selector:update` - Selector updated. The [Selector] and the object containing changes are passed as arguments to the callback. * `selector:state` - States changed. An object containing all the available data about the triggered event is passed as an argument to the callback. * `selector` - 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. ## Methods * [getConfig][2] * [add][3] * [get][4] * [remove][5] * [getAll][6] * [setState][7] * [getState][8] * [getSelected][9] * [addSelected][10] * [removeSelected][11] * [setComponentFirst][12] * [getComponentFirst][13] [Selector]: selector.html ## getConfig Get configuration object Returns **[Object][14]** ## add Add a new selector to the collection if it does not already exist. You can pass selectors properties or string identifiers. ### Parameters * `props` **([Object][14] | [String][15])** Selector properties or string identifiers, eg. `{ name: 'my-class', label: 'My class' }`, `.my-cls` * `opts` **[Object][14]?** Selector options (optional, default `{}`) ### Examples ```javascript const selector = selectorManager.add({ name: 'my-class', label: 'My class' }); console.log(selector.toString()) // `.my-class` // Same as const selector = selectorManager.add('.my-class'); console.log(selector.toString()) // `.my-class` ``` Returns **[Selector]** ## get Get the selector by its name/type ### Parameters * `name` **[String][15]** Selector name or string identifier * `type` ### Examples ```javascript const selector = selectorManager.get('.my-class'); // Get Id const selectorId = selectorManager.get('#my-id'); ``` Returns **([Selector] | null)** ## remove Remove Selector. ### Parameters * `selector` **([String][15] | [Selector])** Selector instance or Selector string identifier * `opts` ### Examples ```javascript const removed = selectorManager.remove('.myclass'); // or by passing the Selector selectorManager.remove(selectorManager.get('.myclass')); ``` Returns **[Selector]** Removed Selector ## setState Change the selector state ### Parameters * `value` **[String][15]** State value ### Examples ```javascript selectorManager.setState('hover'); ``` Returns **this** ## getState Get the current selector state value Returns **[String][15]** ## getStates Get states Returns **[Array][16]\** ## setStates Set a new collection of states ### Parameters * `states` **[Array][16]<[Object][14]>** Array of new states * `opts` ### Examples ```javascript const states = selectorManager.setStates([ { name: 'hover', label: 'Hover' }, { name: 'nth-of-type(2n)', label: 'Even/Odd' } ]); ``` Returns **[Array][16]\** ## getSelected Get commonly selected selectors, based on all selected components. ### Examples ```javascript const selected = selectorManager.getSelected(); console.log(selected.map(s => s.toString())) ``` Returns **[Array][16]<[Selector]>** ## addSelected Add new selector to all selected components. ### Parameters * `props` **([Object][14] | [String][15])** Selector properties or string identifiers, eg. `{ name: 'my-class', label: 'My class' }`, `.my-cls` ### Examples ```javascript selectorManager.addSelected('.new-class'); ``` ## removeSelected Remove a common selector from all selected components. ### Parameters * `selector` **([String][15] | [Selector])** Selector instance or Selector string identifier ### Examples ```javascript selectorManager.removeSelected('.myclass'); ``` ## setComponentFirst Update component-first option. If the component-first is enabled, all the style changes will be applied on selected components (ID rules) instead of selectors (which would change styles on all components with those classes). ### Parameters * `value` **[Boolean][17]** ## getComponentFirst Get the value of component-first option. Returns **[Boolean][17]** ## getAll Get all selectors Returns **Collection<[Selector]>** [1]: https://github.com/artf/grapesjs/blob/master/src/selector_manager/config/config.js [2]: #getconfig [3]: #add [4]: #get [5]: #remove [6]: #getall [7]: #setstate [8]: #getstate [9]: #getselected [10]: #addselected [11]: #removeselected [12]: #setcomponentfirst [13]: #getcomponentfirst [14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array [17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean