# 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:

span > #send-btn.btn{
  <button id="send-btn" class="btn"></button>

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 (opens new window)

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;

# 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

Get configuration object

Returns Object (opens new window)

# add

Add a new selector to the collection if it does not already exist. You can pass selectors properties or string identifiers.

# Parameters

# Examples

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

# Examples

const selector = selectorManager.get('.my-class');
// Get Id
const selectorId = selectorManager.get('#my-id');

Returns (Selector | null)

# remove

Remove Selector.

# Parameters

# Examples

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

Returns Selector Removed Selector

# rename

Rename Selector.

# Parameters

# Examples

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

# Examples


Returns this

# getState

Get the current selector state value

Returns String (opens new window)

# getStates

Get states

Returns Array (opens new window)<State>

# setStates

Set a new collection of states

# Parameters

# Examples

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

Returns Array (opens new window)<State>

# getSelected

Get commonly selected selectors, based on all selected components.

# Examples

const selected = selectorManager.getSelected();
console.log(selected.map(s => s.toString()))

Returns Array (opens new window)<Selector>

# getSelectedAll

Get selected selectors.

# Examples

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

Returns Array (opens new window)<Selector>

# addSelected

Add new selector to all selected components.

# Parameters

# Examples


# removeSelected

Remove a common selector from all selected components.

# Parameters

# Examples


# getSelectedTargets

Get the array of currently selected targets.

# Examples

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

Returns Array (opens new window)<(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

# getComponentFirst

Get the value of component-first option.

Returns Boolean (opens new window)

# getAll

Get all selectors

Returns Collection<Selector>