grapesjs/docs/modules/Style-manager.md

title
Style Manager

Style Manager

The Style Manager module is responsible to show and update style properties relative to your Components. In this guide, you will see how to setup and take full advantage of the built-in Style Manager UI in GrapesJS. The default UI is a lightweight component with built-in properties, but as you'll see next in this guide, it's easy to extend with your own elements or even create the Style Manager UI from scratch by using the Style Manager API.

::: warning To get a better understanding of the content in this guide, we recommend reading Components first ::: ::: warning This guide is referring to GrapesJS v0.17.30 or higher :::

toc

Configuration

To change the default configurations you have to pass the styleManager property with the main configuration object.

const editor = grapesjs.init({
  ...
  styleManager: {
    sectors: [...],
    ...
  }
});

Check the full list of available options here: Style Manager Config

Initialization

The Style Manager module is organized in sectors where each sector contains a list of properties to display. The default Style Manager configuration contains already a list of default common property styles and you can use them by simply skipping the styleManagerConfig.sectors option.

grapesjs.init({
  ...
  styleManager: {
    // With no defined sectors, the default list will be loaded
    // sectors: [...],
    ...
  },
});

::: danger It makes sense to show the Style Manager UI only when you have at least one component selected, so by default the Style Manager is hidden if there are no selected components. :::

Sector defintions

Each sector is identified by its name and a list of properties to display. You can also specify the id in order to access the sector via API (if not indicated it will be generated from the name) and the default open state.

grapesjs.init({
  // ...
  styleManager: {
    sectors: [
      {
        name: 'First sector',
        properties: [],
        // id: 'first-sector', // Id generated from the name
        // open: true, // The sector is open by default
      },
      {
        open: false, // render it closed by default
        name: 'Second sector',
        properties: [],
      },
    ],
  },
});

Property defintions

Once you have defined your sector you can start adding property definitions inside properties. Each property has a common set of options (label, default, etc.) and others specific by their type.

Let's see below a simple definition for controlling the padding style.

sectors: [
  {
    name: 'First sector',
    properties: [
      {
        // Default options
        // id: 'padding', // The id of the property, if missing, will be the same as `property` value
        type: 'number',
        label: 'Padding', // Label for the property
        property: 'padding', // CSS property to change
        default: '0', // Default value to display
        // Additonal `number` options
        units: ['px', '%'], // Units (available only for the 'number' type)
        min: 0, // Min value (available only for the 'number' type)
      }
    ],
  },
]

This will render the number input UI and will change the padding CSS property on the selected component.

The flexibility of the definition allows you to create easily different UI inputs for any possible CSS property. You're free to decide what will be the best UI for your users. If you take for example a numeric property like font-size, you can follow its CSS specification and define it as a number

{
  type: 'number',
  label: 'Font size',
  property: 'font-size',
  units: ['px', '%', 'em', 'rem', 'vh', 'vw'],
  min: 0,
}

or you can decide to show it as a select and make available only a defined set of values (eg. based on your Design System tokens).

{
  type: 'select',
  label: 'Font size',
  property: 'font-size',
  default: '1rem',
  options: [
    { id: '0.7rem', label: 'small' },
    { id: '1rem', label: 'medium' },
    { id: '1.2rem', label: 'large' },
  ]
}

Each type defines the specific UI view and a model on how to handle inputs and updates. Let's see below the list of all available default types with their relative UI and models.

Default types

::: tip Each Model describes more in detail available props and their usage. :::

• base - The base type, renders as a simple text input field. Model: Property

  // Example
  {
    // type: 'base', // Omitting the type in definition will fallback to the 'base'
    property: 'some-css-property',
    label: 'Base type',
    default: 'Default value',
  },
  

• color - Same props as base but the UI is a color picker. Model: Property

• number - Number input field for numeric values. Model: PropertyNumber

  // Example
  {
    type: 'number',
    property: 'width',
    label: 'Number type',
    default: '0%',
    // Additional props
    units: ['px', '%'],
    min: 0,
    max: 100,
  },
  

• slider - Same props as number but the UI is a slider. Model: PropertyNumber

• select - Select input with options. Model: PropertySelect

  // Example
  {
    type: 'select',
    property: 'display',
    label: 'Select type',
    default: 'block',
    // Additional props
    options: [
      {id: 'block', label: 'Block'},
      {id: 'inline', label: 'Inline'},
      {id: 'none', label: 'None'},
    ]
  },
  

• radio - Same props as select but the UI is a radio button. Model: PropertySelect

• composite - This type is great for CSS shorthand properties, where the final value is a composition of multiple sub properties. Model: PropertyComposite

  // Example
  {
    type: 'composite',
    property: 'margin',
    label: 'Composite type',
    // Additional props
    properties: [
      { type: 'number', units: ['px'], default: '0', property: 'margin-top' },
      { type: 'number', units: ['px'], default: '0', property: 'margin-right' },
      { type: 'number', units: ['px'], default: '0', property: 'margin-bottom' },
      { type: 'number', units: ['px'], default: '0', property: 'margin-left' },
    ]
  },
  

• stack - This type is great for CSS multiple properties like text-shadow, box-shadow, transform, etc. Model: PropertyStack

  // Example
  {
    type: 'stack',
    property: 'text-shadow',
    label: 'Stack type',
    // Additional props
    properties: [
      { type: 'number', units: ['px'], default: '0', property: 'x' },
      { type: 'number', units: ['px'], default: '0', property: 'y' },
      { type: 'number', units: ['px'], default: '0', property: 'blur' },
      { type: 'color', default: 'black', property: 'color' },
    ]
  },
  

Built-in properties

In order to speed up the Style Manager configuration, GrapesJS is shipped with a set of already defined common CSS properties which you can reuse and extend.

sectors: [
  {
    name: 'First sector',
    properties: [
      // Pass the built-in CSS property as a string
      'width',
      'min-width',
      // Extend the built-in property with your props
      {
        extend: 'max-width',
        units: ['px', '%'],
      },
      // If the property doesn't exist it will be converted to a base type
      'unknown-property' // -> { type: 'base', property: 'unknown-property' }
    ],
  },
]

::: tip You can check if the property is available by running

editor.StyleManager.getBuiltIn('property-name');

or get the list of all available properties with

editor.StyleManager.getBuiltInAll();

:::

I18n

If you're planning to have a multi-language editor you can easily connect sector and property labels to the I18n module via their IDs.

grapesjs.init({
  styleManager: {
    sectors: [
      {
        id: 'first-sector-id',
        // You can leave the name as a fallback in case the i18n definition is missing
        name: 'First sector',
        properties: [
          'width',
          {
            id: 'display-prop-id', // By default the id is the same as its property name
            label: 'Display',
            type: 'select',
            property: 'display',
            default: 'block',
            options: [
              {id: 'block', label: 'Block'},
              {id: 'inline', label: 'Inline'},
              {id: 'none', label: 'None'},
            ]
          },
        ],
      },
      // ...
    ],
  },
  i18n: {
    // Use `messagesAdd` in order to extend the default set
    messagesAdd: {
      en: {
        styleManager: {
          sectors: {
            'first-sector-id': 'First sector EN'
          },
          properties: {
            width: 'Width EN',
            'display-prop-id': 'Display EN',
          },
          options: {
            'display-prop-id': {
              block: 'Block EN',
              inline: 'Inline EN',
              none: 'None EN',
            }
          }
        }
      }
    }
  },
});

Components constraints

When you define custom components you can also indicate, via stylable and unstylable props, which CSS properties should be available for styling. In that case, the Style Manager will only show the available properties. If the sector doesn't contain any available property, it won't be shown.

const customComponents = (editor) => {
  // Component A
  editor.Components.addType('cmp-a', {
    model: {
      defaults: {
        // When this component is selected, the Style Manager will show only the following properties
        stylable: ['width', 'height']
      }
    }
  });
  // Component B
  editor.Components.addType('cmp-b', {
    model: {
      defaults: {
        // When this component is selected, the Style Manager will hide the following properties
        unstylable: ['color']
      }
    }
  });
};

grapesjs.init({
  // ...
  plugins: [customComponents],
  components: [
    { type: 'cmp-a', components: 'Component A' },
    { type: 'cmp-b', components: 'Component B' },
  ],
  styleManager: {
    sectors: [
      {
        name: 'First sector',
        properties: [
          'width', 'min-width',
          'height', 'min-height',
        ],
      },
      {
        name: 'Second sector',
        properties: [
          'color', 'font-size',
        ],
      },
    ],
  },
});

Programmatic usage

For a more advanced usage you can rely on the Style Manager API to perform different kind of actions related to the module.

• Managing sectors/properties post-initialization.

  // Get the module from the editor instance
  const sm = editor.StyleManager;
  
  // Add new sector
  const newSector = sm.addSector('sector-id', {
    name: 'New sector',
    open: true,
    properties: ['width'],
  });
  
  // Add new property to the sector
  sm.addProperty('sector-id', {
    type: 'number',
    property: 'min-width',
  });
  
  // Remove sector
  sm.removeSector('sector-id');
  

• Managing selected targets.

  // Select the first button in the current page
  const wrapperCmp = editor.Pages.getSelected().getMainComponent();
  const btnCmp = wrapperCmp.find('button')[0];
  btnCmp && sm.select(btnCmp);
  
  // Set as a target the CSS selector (the relative CSSRule will be created if doesn't exist yet)
  sm.select('.btn > span');
  // Get the last selected target
  const lastTarget = sm.getLastSelected();
  lastTarget?.toCSS && console.log(lastTarget.toCSS());
  
  // Update selected targets with a custom style
  sm.addStyleTargets({ color: 'red' });
  

• Adding/extending built-in property definitions.

  const myPlugin = (editor) => {
    editor.StyleManager.addBuiltIn('new-prop', {
      type: 'number',
      label: 'New prop',
    })
  };
  
  grapesjs.init({
    // ...
    plugins: [myPlugin],
    styleManager: {
      sectors: [
        {
          name: 'My sector',
          properties: [ 'new-prop', ... ],
        },
      ],
    },
  })
  

• Adding new types.

Customization

The default types should cover most of the common styling properties but in case you need a more advanced control over styling you can define your own types or even create a completely custom Style Manager UI from scratch.

Adding new types

In order to add a new type you have to use the styleManager.addType API call and indicate all the necessary methods to make it work properly with the editor. Here an example of implementation by using the native range input.

styleManager.addType('my-custom-prop', {
   // Create UI
   create({ props, change }) {
     const el = document.createElement('div');
     el.innerHTML = '<input type="range" class="my-input" min="10" max="50"/>';
     const inputEl = el.querySelector('.my-input');
     inputEl.addEventListener('change', event => change({ event })); // `change` will trigger the emit
     inputEl.addEventListener('input', event => change({ event, complete: false }));
     return el;
   },
   // Propagate UI changes up to the targets
   emit({ props, updateStyle }, { event, complete }) {
     const { value } = event.target;
     const valueRes = value + 'px';
     // Pass a string value for the current CSS property or an object containing multiple properties
     updateStyle(valueRes, { complete });
     // Update target style with multiple properties
     // eg. updateStyle({ [props.property]: valueRes, color: 'red' });
   },
   // Update UI (eg. when the target is changed)
   update({ value, el }) {
     el.querySelector('.my-input').value = parseInt(value, 10);
   },
   // Clean the memory from side effects if necessary (eg. event listeners)
   destroy() {
   }
})

Custom Style Manager

Events

For a complete list of available events, you can check it here.