grapesjs/docs/api/selector_manager.md

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:

span > #send-btn.btn{
 ...
}

<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

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.

// 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 - State changed. Passes the new state value as an argument.
• 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
• add
• addClass
• get
• getAll
• setState
• getState

init

Get configuration object

Parameters

• conf (optional, default {})

Returns Object

setState

Change the selector state

Parameters

• value String State value

Examples

selectorManager.setState('hover');

Returns this

getState

Get the current selector state

Returns String

add

Add a new selector to collection if it's not already exists. Class type is a default one

Parameters

• name (String | Array) Selector/s name

• opts Object Selector options (optional, default {})

  • opts.label String Label for the selector, if it's not provided the label will be the same as the name (optional, default '')
  • opts.type String Type of the selector. At the moment, only 'class' (1) is available (optional, default 1)

Examples

const selector = selectorManager.add('selectorName');
// Same as
const selector = selectorManager.add('selectorName', {
  type: 1,
  label: 'selectorName'
});
// Multiple selectors
const selectors = selectorManager.add(['.class1', '.class2', '#id1']);

Returns (Model | Array)

addClass

Add class selectors

Parameters

• classes (Array | string) Array or string of classes

Examples

sm.addClass('class1');
sm.addClass('class1 class2');
sm.addClass(['class1', 'class2']);
// -> [SelectorObject, ...]

Returns Array Array of added selectors

get

Get the selector by its name

Parameters

• name (String | Array) Selector name
• type String Selector type

Examples

const selector = selectorManager.get('selectorName');
// or get an array
const selectors = selectorManager.get(['class1', 'class2']);

Returns (Model | Array)

getAll

Get all selectors

Returns Collection

escapeName

Return escaped selector name

Parameters

• name String Selector name to escape

Returns String Escaped name