Documentation / Settings

Formatting

breakline #

Type: Boolean

Default: false

This setting allows you to use br tag on the enter pressed markup instead of p tag.

$R('#content', {
        breakline: true
});

markup #

Type: String

Default: p

By default Redactor creates paragraph on the enter key pressed. You can change it:

$R('#content', {
        markup: 'div'
});

enterKey #

Type: Boolean

Default: true

This setting allows to prevent use of Return/Enter key.

$R('#content', {
        enterKey: false
});

With this set to 'false' and pastePlainText is set to true, line breaks will be replaced by spaces.

formatting #

Type: Array

Default: ['p', 'blockquote', 'pre', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']

This setting allows to adjust a list of formatting tags in the default formatting dropdown. For example, following settings will only show 'Normal', 'Blockquote' and 'Header 2' in the formatting dropdown:

$R('#content', {
        formatting: ['p', 'blockquote', 'h2']
});

You can customize this by adding your own tags and CSS classes by setting formattingAdd.

formattingAdd #

Type: Boolean Object

Default: false

This setting allows to create a custom set of formatting options for Formatting dropdown.

formattingAdd can only be applied to block tags (p, pre, blockquote, div, heading, etc).

Here's an example of adding options to apply and remove Red Block and Blue Heading, toggling class of a paragraph, and also toggle some attributes:

$R('#content', {
        formattingAdd: {
            "red-p-add": {
                title: 'Red Paragraph',
                api: 'module.block.format',
                args: {
                    'tag': 'p',
                    'class': 'red-styled'
                }
            },
            "red-p-remove": {
                title: 'Red Paragraph Remove',
                api: 'module.block.format',
                args: {
                    'tag': 'p',
                    'class': 'red-styled',
                    'type': 'remove'
                }
            },
            "blue-heading": {
                title: 'Blue Heading',
                api: 'module.block.format',
                args: {
                    'tag': 'h3',
                    'class': 'blue-styled',
                    'type': 'toggle'
                }
            },
            "toggle-attr": {
                title: 'Toggle attributes and style',
                api: 'module.block.format',
                args: {
                    'tag': 'p',
                    'attr': {
                        'data-toggle': 'modal',
                        'class': 'my-class'
                    },
                    'style': {
                        'color': 'yellow'
                    },
                    'type': 'toggle'
                }
            }
        }
    });

Each style here is an object, that must consist of name (blue-heading), title ("Blue Heading"), API method and an object of arguments:

"style-name": {
    title: 'Title for dropdown item',
    api: 'module.block.format',
    args: 'object-of-arguments'
}

Style name can only contain letter, numbers and dashes. Redactor will automatically assign CSS class by name so that you could style dropdown elements.

.redactor-dropdown-format .redactor-dropdown-item-red-p-add
.redactor-dropdown-format .redactor-dropdown-item-red-p-remove
.redactor-dropdown-format .redactor-dropdown-item-blue-header
.redactor-dropdown-format .redactor-dropdown-item-toggle-attr
// etc

By default, when a user applies style, all existing styles of the block will be removed or replaced with the new style. However, there is a way to prevent this by using type parameter: add, remove or toggle.

The type argument:

  • set (by default) - removes all classes, styles or attributes and applies the new value.
  • add - adds the new value, but doesn't remove or replace existing classes, styles or attributes.
  • toggle - adds the new value if this value didn't exist, and removes it, if the value did exist. No other values will be removed.
  • remove - removes selected value.

formattingHide #

Type: Boolean Array

Default: false

This setting allows to hide some tags from the formatting dropdown.

$R('#content', {
        formattingHide: ['pre', 'h4', 'h5', 'h6']
});