TINY NEWS: TinyMCE 5 Developer Challenge now on.  Find out more

Content formatting options

These settings change the way the editor handles the input and output of content. This will help you to create clean, maintainable and readable content.

Contribute to this page

block_formats

List of formats to be displayed under formatselect dropdown. Each item in the list should be specified in a form of: title=block and separated by semi-colon.

Type: String

Default Value: 'Paragraph=p;Heading 1=h1;Heading 2=h2;Heading 3=h3;Heading 4=h4;Heading 5=h5;Heading 6=h6;Preformatted=pre'

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your html
  block_formats: 'Paragraph=p;Header 1=h1;Header 2=h2;Header 3=h3'
});

font_formats

List of fonts to be displayed under fontselect dropdown. Each item in the list should be specified in a form of: title=font-family and separated by semi-colon.

Type: String

Default Value: 'Andale Mono=andale mono,times;Arial=arial,helvetica,sans-serif;Arial Black=arial black,avant garde;Book Antiqua=book antiqua,palatino;Comic Sans MS=comic sans ms,sans-serif;Courier New=courier new,courier;Georgia=georgia,palatino;Helvetica=helvetica;Impact=impact,chicago;Symbol=symbol;Tahoma=tahoma,arial,helvetica,sans-serif;Terminal=terminal,monaco;Times New Roman=times new roman,times;Trebuchet MS=trebuchet ms,geneva;Verdana=verdana,geneva;Webdings=webdings;Wingdings=wingdings,zapf dingbats'

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  toolbar: 'fontselect',
  font_formats: 'Arial=arial,helvetica,sans-serif;Courier New=courier new,courier,monospace;AkrutiKndPadmini=Akpdmi-n'
});

fontsize_formats

This option allows you to override the font sizes displayed in the font size select box using a space or comma separated list of font sizes.

Type: String

Default Value: '11px 12px 14px 16px 18px 24px 36px 48px'

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  toolbar: 'fontsizeselect',
  fontsize_formats: '11px 12px 14px 16px 18px 24px 36px 48px'
});

formats

The format options are used to override and add custom formats to the editor.

For example, a format is a style that gets applied to text when the bold button is enabled inside the editor. TinyMCE is equipped with a text formatting engine that allows specifying what it should produce when the user clicks (in this example) the bold button.

Check out the custom formats example for a demonstration of this option.

Formats are objects where the value is either an object with format options or an array of format variants.

When a format is applied the first item, the formats array will be applied. However, when trying to match the format to remove or update the UI, the other formats in the array is considered as well. So the first format is a kind of primary format, and the rest are secondary formats.

The following is an example of an array of format variants:

bold: [
     { inline: 'strong', remove: 'all' },
     { inline: 'span', styles: { fontWeight: 'bold' } },
     { inline: 'b', remove: 'all' }
   ],

Style merging

Similar elements and styles are merged by default to reduce the output HTML size. So for example, if a font size and font face are selected for a word, it merges these two styles into one span element instead of one span for each format type.

Built-in formats

TinyMCE has some built in formats that can be overridden. These are:

  • alignleft
  • aligncenter
  • alignright
  • alignjustify
  • bold
  • italic
  • underline
  • strikethrough
  • forecolor
  • hilitecolor
  • fontname
  • fontsize
  • blockquote
  • removeformat
  • p
  • h1, h2, h3, h4, h5, h6
  • div
  • address
  • pre
  • div
  • code
  • dt, dd
  • samp

Some built-in formats fontsize, fontname, forecolor, hilitecolor uses a variable in their definition named %value. This one gets replaced with the user selected item such as a color value. Check the variable substitution section below for details.

Format Type

There are three format types that the default classes can be applied to:

  • Block format
  • Inline format
  • Selector format

block

Tag name of the block element to use as a wrapper, for example, h1. Existing block elements within the selection are replaced with this block element.

Type: string

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    // Changes the default format for h1 to have a class of heading
    h1: { block: 'h1', classes: 'heading' }
  },
  style_formats: [
    // Adds a h1 format to the formats select dropdown
    { title: 'My heading', block: 'h1', classes: 'heading' }
  ]
});

inline

Tag name of the inline element to use as a wrapper, for example, span is used to wrap the current selection.

Type: string

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    // Changes the default format for the bold button to produce a span with a bold class
    bold: { inline: 'span', classes: 'bold' }
  },
  style_formats: [
    // Adds a my bold format to the formats select dropdown
    { title: 'My bold', inline: 'span', classes: 'bold' }
  ]
});

selector

CSS3 selector pattern that is used to find elements within the selection. It can be used to apply classes to specific elements only, for example only to odd rows in a table.

Type: string

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    // Changes the alignment buttons to add a class to each of the matching selector elements
    alignleft: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'left' },
    aligncenter: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'center' },
    alignright: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'right' },
    alignjustify: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'full' }
  },
  style_formats: [
    // Adds alignment formats to the formats dropdown
    { title: 'Align left', selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'left' },
    { title: 'Align center', selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'center' },
    { title: 'Align right', selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'right' },
    { title: 'Align justify', selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'full' }
  ]
});

Format parameters

For each format some additional parameters can be specified:

classes

Space-separated list of classes that are applied to the selected or newly created inline/block element.

Type: string

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    // Changes the default format for the bold button to produce a span with a bold class
    bold: { inline: 'span', classes: 'bold' }
  },
  style_formats: [
    // Adds bold format to the formats dropdown
    { title: 'My bold', inline: 'span', classes: 'bold' }
  ]
});

styles

Key/value object with CSS styles to apply to the selected or newly created inline/block element (e.g. color, backgroundColor, textDecoration, etc).

Type: Object

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    // Changes the default format for the bold button to produce a span with style with font-width: bold
    bold: { inline: 'span', styles: { 'font-weight': 'bold' } }
  },
  style_formats: [
    // Adds bold format to the formats dropdown
    { title: 'My bold', inline: 'span', styles: { 'font-weight': 'bold' } }
  ]
});

attributes

Key/value object with attributes to apply to the selected or newly created inline/block element.

Type: Object

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    // Changes the default format for the bold button to produce a strong with data-style attribute
    bold: { inline: 'strong', attributes: { 'data-style': 'bold' } }
  },
  style_formats: [
    // Adds bold format to the formats dropdown
    { title: 'My bold', inline: 'strong', attributes: { 'data-style': 'bold' } }
  ]
});

exact

Makes sure that the format is not merged with other wrappers having the same format. We use it to avoid conflicts between text-decorations for underline and strikethrough formats.

Type: boolean

Default: false

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    // Changes the default format for the underline button to produce a span with a class and not merge that underline into parent spans
    underline: { inline: 'span', styles: { 'text-decoration': 'underline' }, exact: true },
    strikethrough: { inline: 'span', styles: { 'text-decoration': 'line-through' }, exact: true }
  }
});

wrapper

States that the format is a container format for block elements. For example, a div wrapper or blockquote.

Type: boolean

Default: false

Example
tinymce.init({
  selector: 'textarea',
  style_formats: [
    // A custom format that wraps blocks into a div with the specified wrapper class
    { title: 'My custom format', block: 'div', classes: 'wrapper', wrapper: true }
  ]
});

remove

Specifies what the remove behavior of the element should be when the format is removed.

Type: string

Default: none for selector formats empty for all other format types.

This can be set to three different modes:

  • none: Only styles, classes or attributes are removed from the element the element is never removed.
  • empty: If the element has no styles, classes, or attributes then the element is removed.
  • all: Removes the element regardless of its styles, classes, and or attributes.
Example
tinymce.init({
  selector: 'textarea',
  extended_valid_elements: 'span[*]', // Needed to retain spans without attributes these are removed by default
  formats: {
    removeformat: [
      // Configures `clear formatting` to remove specified elements regardless of it's attributes
      { selector: 'b,strong,em,i,font,u,strike', remove: 'all' },

      // Configures `clear formatting` to remove the class red from spans and if the element then becomes empty i.e has no attributes it gets removed
      { selector: 'span', classes: 'red', remove: 'empty' },

      // Configures `clear formatting` to remove the class green from spans and if the element then becomes empty it's left intact
      { selector: 'span', classes: 'green', remove: 'none' }
    ]
  }
});

block_expand

This option controls if the selection should expand upwards to the closest matching block element. This can be useful when configuring removeformat to remove block elements. So if the selection start is at the beginning of a matching block, then that matching block will be included as well. If the end of the selection is at the end of a matching block element then that parent element will be included as well.

So if the selection is from a to b in this html contents <h1><b>[a</b></h1><p>b]</p> then the h1 will be removed even if it’s not part of the actual selection.

Type: boolean

Example
tinymce.init({
  selector: 'textarea',
  formats: {
    removeformat: [
      {
        selector: 'h1,h2,h3,h4,h5,h6',
        remove: 'all',
        split: false,
        expand: false,
        block_expand: true,
        deep: true
      },
      {
        selector: 'a,b,strong,em,i,font,u,strike,sub,sup,dfn,code,samp,kbd,var,cite,mark,q,del,ins',
        remove: 'all',
        split: true,
        expand: false,
        deep: true
      },
      { selector: 'span', attributes: ['style', 'class'], remove: 'empty', split: true, expand: false, deep: true },
      { selector: '*', attributes: ['style', 'class'], split: false, expand: false, deep: true }
    ]
  }
});

deep

Enables control for removing the child elements of the matching format. This is set to false by default on selector formats. As a result, when a class is removed from a selected table class, disabling deep retains the class in the child elements within the other nested tables.

Type: boolean

Default: false for selector formats

Example
tinymce.init({
  selector: 'textarea',
  style_formats: [
    // A custom format that wraps blocks into a div with the specified wrapper class
    { title: 'My custom format', inline: 'span', classes: 'myclass', deep: false }
  ]
});

Example of usage of the formats option

This example overrides some of the built-in formats and tells TinyMCE to apply classes instead of inline styles. It also includes a custom format that produced h1 elements with a title attribute and a red CSS style.

Type: Object

Example
// Output elements in HTML style
tinymce.init({
  selector: 'textarea',  // change this value according to your html
  formats: {
    alignleft: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'left' },
    aligncenter: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'center' },
    alignright: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'right' },
    alignjustify: { selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'full' },
    bold: { inline: 'span', classes: 'bold' },
    italic: { inline: 'span', classes: 'italic' },
    underline: { inline: 'span', classes: 'underline', exact: true },
    strikethrough: { inline: 'del' },
    forecolor: { inline: 'span', classes: 'forecolor', styles: { color: '%value' } },
    hilitecolor: { inline: 'span', classes: 'hilitecolor', styles: { backgroundColor: '%value' } },
    custom_format: { block: 'h1', attributes: { title: 'Header' }, styles: { color: 'red' } }
  }
});

Using custom formats

Custom formats can be handled through the TinyMCE API. Here is a basic example of usage for the custom format defined above.

// Applying the specified format
tinymce.activeEditor.formatter.apply('custom_format');

// Removing the specified format
tinymce.activeEditor.formatter.remove('custom_format');

Variable substitution

Variables can be used in the format definition. These variables are then replaced with the ones specified in the call to the apply function. Here is an example of how to use variables within formats.

// Registering the special format with a variable
tinymce.activeEditor.formatter.register('custom_format', { inline: 'span', styles: { color: '%value' } });

// Applying the specified format with the variable specified
tinymce.activeEditor.formatter.apply('custom_format', { value: 'red' });

Removing a format

Use the removeformat option specify how the clear formatting feature should work in the editor.

Type: Array

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  formats: {
    removeformat: [
      {
        selector: 'b,strong,em,i,font,u,strike,sub,sup,dfn,code,samp,kbd,var,cite,mark,q,del,ins',
        remove: 'all',
        split: true,
        block_expand: true,
        expand: false,
        deep: true
      },
      { selector: 'span', attributes: ['style', 'class'], remove: 'empty', split: true, expand: false, deep: true },
      { selector: '*', attributes: ['style', 'class'], split: false, expand: false, deep: true }
    ]
  }
});

indentation

The indentation option allows specification of the indentation level for indent/outdent buttons in the UI.

The indentation option defaults to 30px but can be any value.

Type: String

Default Value: 30px

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  indentation : '20pt'
});

indent_use_margin

The indent_use_margin option is set if the editor should use margin instead of padding when indenting content.

Type: boolean

Default Value: false

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  indentation : '20pt',
  indent_use_margin: true
});

style_formats

This option enables you to add more advanced style formats for text and other elements to the editor. The value of this option will be rendered as styles in the styleselect dropdown toolbar item.

It’s important to note that the style_formats option, while similar in syntax, is entirely separate from the formats option. For a complete reference of the different format options then check the formats

Type: Array

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your html
  toolbar: "styleselect",
  style_formats: [
    {title: 'Bold text', inline: 'b'},
    {title: 'Red text', inline: 'span', styles: {color: '#ff0000'}},
    {title: 'Red header', block: 'h1', styles: {color: '#ff0000'}},
    {title: 'Example 1', inline: 'span', classes: 'example1'},
    {title: 'Example 2', inline: 'span', classes: 'example2'},
    {title: 'Table styles'},
    {title: 'Table row 1', selector: 'tr', classes: 'tablerow1'}
  ]
});

Another example, this will add two options to the Formats dropdown, one for aligning an image left and adding a margin, one for putting it on the right side and setting a margin.

Type: Array

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  toolbar: "styleselect",
  style_formats: [
    {
      title: 'Image Left',
      selector: 'img',
      styles: {
        'float': 'left',
        'margin': '0 10px 0 10px'
      }
    },
    {
      title: 'Image Right',
      selector: 'img',
      styles: {
        'float': 'right',
        'margin': '0 0 10px 10px'
      }
    }
  ]
});

A live demo of this option can be found in the custom formats example.

If you want to merge your styles to the default styles_format, you can use the style_formats_merge settings:

Type: Boolean

Default Value: false

Possible Values: true, false

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  toolbar: "styleselect",
  style_formats_merge: true,
  style_formats: [
      // Your format as described on this page
  ]
});

The default is very similar to the following:

Type: Array

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  toolbar: "styleselect",
  style_formats: [
    {title: 'Headers', items: [
      {title: 'Header 1', format: 'h1'},
      {title: 'Header 2', format: 'h2'},
      {title: 'Header 3', format: 'h3'},
      {title: 'Header 4', format: 'h4'},
      {title: 'Header 5', format: 'h5'},
      {title: 'Header 6', format: 'h6'}
    ]},
    {title: 'Inline', items: [
      {title: 'Bold', icon: 'bold', format: 'bold'},
      {title: 'Italic', icon: 'italic', format: 'italic'},
      {title: 'Underline', icon: 'underline', format: 'underline'},
      {title: 'Strikethrough', icon: 'strikethrough', format: 'strikethrough'},
      {title: 'Superscript', icon: 'superscript', format: 'superscript'},
      {title: 'Subscript', icon: 'subscript', format: 'subscript'},
      {title: 'Code', icon: 'code', format: 'code'}
    ]},
    {title: 'Blocks', items: [
      {title: 'Paragraph', format: 'p'},
      {title: 'Blockquote', format: 'blockquote'},
      {title: 'Div', format: 'div'},
      {title: 'Pre', format: 'pre'}
    ]},
    {title: 'Alignment', items: [
      {title: 'Left', icon: 'alignleft', format: 'alignleft'},
      {title: 'Center', icon: 'aligncenter', format: 'aligncenter'},
      {title: 'Right', icon: 'alignright', format: 'alignright'},
      {title: 'Justify', icon: 'alignjustify', format: 'alignjustify'}
    ]}
  ]
});

Hopefully we’ll have an exact replica of the defaults soon.

style_formats_autohide

This option enables auto hiding of styles that doesn’t match the current context. That means if you have a style for tables only it wouldn’t be visible in the styles drop down when the caret isn’t inside a table.

Type: Boolean Defaults: False

Example
tinymce.init({
  selector: 'textarea',
  style_formats: [
    {title: 'Red cell', selector: 'td', classes: 'red'},
    {title: 'Red text', inline: 'span', styles: {color: '#ff0000'}}
  ],
  style_formats_autohide: true
});

style_formats_merge

This option allows you to set whether TinyMCE should append the styles in the style_formats setting to the default style formats or completely replace them.

Type: Boolean
Defaults: False

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  style_formats: [
    {title: 'Bold text', inline: 'b'},
    {title: 'Red text', inline: 'span', styles: {color: '#ff0000'}}
  ],
  style_formats_merge: true
});

Can't find what you're looking for? Let us know.

Except as otherwise noted, the content of this page is licensed under the Creative Commons BY-NC-SA 3.0 License, and code samples are licensed under the Apache 2.0 License.