<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## Selectors

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
<span>
  <button id="send-btn" class="btn"></button>
</span>
```

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]
*   [rename][6]
*   [getAll][7]
*   [setState][8]
*   [getState][9]
*   [getStates][10]
*   [setStates][11]
*   [getSelected][12]
*   [addSelected][13]
*   [removeSelected][14]
*   [getSelectedTargets][15]
*   [setComponentFirst][16]
*   [getComponentFirst][17]

[Selector]: selector.html

[State]: state.html

[Component]: component.html

[CssRule]: css_rule.html

## getConfig

Get configuration object

Returns **[Object][18]** 

## 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][18] | [String][19])** Selector properties or string identifiers, eg. `{ name: 'my-class', label: 'My class' }`, `.my-cls`
*   `opts` **[Object][18]?** 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][19]** Selector name or string identifier
*   `type` **[number][20]?** 

### 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][19] | [Selector])** Selector instance or Selector string identifier
*   `opts` **RemoveOptions?** 

### Examples

```javascript
const removed = selectorManager.remove('.myclass');
// or by passing the Selector
selectorManager.remove(selectorManager.get('.myclass'));
```

Returns **[Selector]** Removed Selector

## rename

Rename Selector.

### Parameters

*   `selector` **[Selector]** Selector to update.
*   `name` **[String][19]** New name for the selector.
*   `opts` **SetOptions?** 

### Examples

```javascript
const selector = selectorManager.get('myclass');
const result = selectorManager.rename(selector, 'myclass2');
console.log(result === selector ? 'Selector updated' : 'Selector with this name exists already');
```

Returns **[Selector]** Selector containing the passed name.

## setState

Change the selector state

### Parameters

*   `value` **[String][19]** State value

### Examples

```javascript
selectorManager.setState('hover');
```

Returns **this** 

## getState

Get the current selector state value

Returns **[String][19]** 

## getStates

Get states

Returns **[Array][21]<[State]>** 

## setStates

Set a new collection of states

### Parameters

*   `states` **[Array][21]<[Object][18]>** Array of new states
*   `opts` **any?** 

### Examples

```javascript
const states = selectorManager.setStates([
  { name: 'hover', label: 'Hover' },
  { name: 'nth-of-type(2n)', label: 'Even/Odd' }
]);
```

Returns **[Array][21]<[State]>** 

## 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][21]<[Selector]>** 

## getSelectedAll

Get selected selectors.

### Examples

```javascript
const selected = selectorManager.getSelectedAll();
console.log(selected.map(s => s.toString()))
```

Returns **[Array][21]<[Selector]>** 

## addSelected

Add new selector to all selected components.

### Parameters

*   `props` **([Object][18] | [String][19])** 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][19] | [Selector])** Selector instance or Selector string identifier

### Examples

```javascript
selectorManager.removeSelected('.myclass');
```

## getSelectedTargets

Get the array of currently selected targets.

### Examples

```javascript
const targetsToStyle = selectorManager.getSelectedTargets();
console.log(targetsToStyle.map(target => target.getSelectorsString()))
```

Returns **[Array][21]<([Component] | [CssRule])>** 

## 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][22]** 

## getComponentFirst

Get the value of component-first option.

Returns **[Boolean][22]** 

## getAll

Get all selectors

Returns **Collection<[Selector]>** 

[1]: https://github.com/GrapesJS/grapesjs/blob/master/src/selector_manager/config/config.ts

[2]: #getconfig

[3]: #add

[4]: #get

[5]: #remove

[6]: #rename

[7]: #getall

[8]: #setstate

[9]: #getstate

[10]: #getstates

[11]: #setstates

[12]: #getselected

[13]: #addselected

[14]: #removeselected

[15]: #getselectedtargets

[16]: #setcomponentfirst

[17]: #getcomponentfirst

[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean