Report an issue


class since 4.1.0

Highly configurable class which implements input data filtering mechanisms and core functions used for the activation of editor features.

A filter instance is always available under the CKEDITOR.editor.filter property and is used by the editor in its core features like filtering input data, applying data transformations, validating whether a feature may be enabled for the current setup. It may be configured in two ways:

In both cases additional allowed content rules may be added by setting the CKEDITOR.config.extraAllowedContent configuration option.

Note: Filter rules will be extended with the following elements depending on the CKEDITOR.config.enterMode and CKEDITOR.config.shiftEnterMode settings:

Read more about Advanced Content Filter in guides.

A filter may also be used as a standalone instance by passing CKEDITOR.filter.allowedContentRules instead of CKEDITOR.editor to the constructor:

var filter = new CKEDITOR.filter( 'b' );

filter.check( 'b' ); // -> true
filter.check( 'i' ); // -> false
filter.allow( 'i' );
filter.check( 'i' ); // -> true

If the filter is only used by a single editor instance, you should pass the editor instance alongside with the rules. Passing the editor as the first parameter binds it with the filter so the filter can be removed with the CKEDITOR.editor.destroy method to prevent memory leaks.

// In both cases the filter will be removed during the CKEDITOR.editor.destroy function execution.
var filter1 = new CKEDITOR.filter( editor );
var filter2 = new CKEDITOR.filter( editor, 'b' );



Static properties


  • constructor( editorOrRules, [ rules ] ) → filter

    Creates a filter class instance.


    editorOrRules : editor | allowedContentRules
    [ rules ] : allowedContentRules

    This parameter is available since 4.11.0.


  • addContentForms( forms )

    Adds an array of CKEDITOR.feature content forms. All forms will then be transformed to the first form which is allowed by the filter.

    editor.filter.allow( 'i; span{!font-style}' );
    editor.filter.addContentForms( [
        [ 'span', function( el ) {
            return el.styles[ 'font-style' ] == 'italic';
        } ]
    ] );
    // Now <em> and <span style="font-style:italic"> will be replaced with <i>
    // because this is the first allowed form.
    // <span> is allowed too, but it is the last form and
    // additionaly, the editor cannot transform an element based on
    // the array+function form).

    This method is used by the editor to register CKEDITOR.feature.contentForms when adding a feature with addFeature or CKEDITOR.editor.addFeature.


    forms : Array

    The content forms of a feature.

  • since 4.4.0

    addElementCallback( callback )

    Adds a callback which will be executed on every element that the filter reaches when filtering, before the element is filtered.

    By returning CKEDITOR.FILTER_SKIP_TREE it is possible to skip filtering of the current element and all its ancestors.

    editor.filter.addElementCallback( function( el ) {
        if ( el.hasClass( 'protected' ) )
            return CKEDITOR.FILTER_SKIP_TREE;
    } );

    Note: At this stage the element passed to the callback does not contain attributes, classes, and styles properties which are available temporarily on later stages of the filtering process. Therefore you need to use the pure CKEDITOR.htmlParser.element interface.


    callback : Function

    The callback to be executed.

  • addFeature( feature ) → Boolean

    Checks whether a feature can be enabled for the HTML restrictions in place for the current CKEditor instance, based on the HTML code the feature might generate and the minimal HTML code the feature needs to be able to generate.

    // TODO example


    feature : feature



    Whether this feature can be enabled.

  • addTransformations( transformations )

    Adds an array of content transformation groups. One group may contain many transformation rules, but only the first matching rule in a group is executed.

    A single transformation rule is an object with four properties:

    • check (optional) – if set and CKEDITOR.filter does not accept this CKEDITOR.filter.contentRule, this transformation rule will not be executed (it does not match). This value is passed to check.
    • element (optional) – this string property tells the filter on which element this transformation can be run. It is optional, because the element name can be obtained from check (if it is a String format) or left (if it is a instance).
    • left (optional) – a function accepting an element or a instance verifying whether the transformation should be executed on this specific element. If it returns false or if an element does not match this style, this transformation rule does not match.
    • right – a function accepting an element and CKEDITOR.filter.transformationsTools or a string containing the name of the CKEDITOR.filter.transformationsTools method that should be called on an element.

    A shorthand format is also available. A transformation rule can be defined by a single string 'check:right'. The string before ':' will be used as the check property and the second part as the right property.

    Transformation rules can be grouped. The filter will try to apply the first rule in a group. If it matches, the filter will ignore subsequent rules and will move to the next group. If it does not match, the next rule will be checked.


    editor.filter.addTransformations( [
        // First group.
            // First rule. If table{width} is allowed, it
            // executes CKEDITOR.filter.transformationsTools.sizeToStyle on a table element.
            'table{width}: sizeToStyle',
            // Second rule should not be executed if the first was.
            'table[width]: sizeToAttribute'
        // Second group.
            // This rule will add the foo="1" attribute to all images that
            // do not have it.
                element: 'img',
                left: function( el ) {
                    return !;
                right: function( el, tools ) {
           = '1';
    ] );
    // Case 1:
    // config.allowedContent = 'table{height,width}; tr td'.
    // '<table style="height:100px; width:200px">...</table>'       -> '<table style="height:100px; width:200px">...</table>'
    // '<table height="100" width="200">...</table>'                -> '<table style="height:100px; width:200px">...</table>'
    // Case 2:
    // config.allowedContent = 'table[height,width]; tr td'.
    // '<table style="height:100px; width:200px">...</table>'       -> '<table height="100" width="200">...</table>'
    // '<table height="100" width="200">...</table>'                -> '<table height="100" width="200"">...</table>'
    // Case 3:
    // config.allowedContent = 'table{width,height}[height,width]; tr td'.
    // '<table style="height:100px; width:200px">...</table>'       -> '<table style="height:100px; width:200px">...</table>'
    // '<table height="100" width="200">...</table>'                -> '<table style="height:100px; width:200px">...</table>'
    // Note: Both forms are allowed (size set by style and by attributes), but only
    // the first transformation is applied &mdash; the size is always transformed to a style.
    // This is because only the first transformation matching allowed content rules is applied.

    This method is used by the editor to add CKEDITOR.feature.contentTransformations when adding a feature by addFeature or CKEDITOR.editor.addFeature.


    transformations : Array
  • allow( newRules, [ featureName ], [ overrideCustom ] ) → Boolean

    Adds allowed content rules to the filter.

    Read about rules formats in Allowed Content Rules guide.

    // Add a basic rule for custom image feature (e.g. 'MyImage' button).
    editor.filter.allow( 'img[!src,alt]', 'MyImage' );
    // Add rules for two header styles allowed by 'HeadersCombo'.
    var header1Style = new { element: 'h1' } ),
        header2Style = new { element: 'h2' } );
    editor.filter.allow( [ header1Style, header2Style ], 'HeadersCombo' );


    newRules : allowedContentRules

    Rule(s) to be added.

    [ featureName ] : String

    Name of a feature that allows this content (most often plugin/button/command name).

    [ overrideCustom ] : Boolean

    By default this method will reject any rules if CKEDITOR.config.allowedContent is defined to avoid overriding it. Pass true to force rules addition.



    Whether the rules were accepted.

  • applyTo( fragment, [ toHtml ], [ transformOnly ], [ enterMode ] ) → Boolean

    Applies this filter to passed CKEDITOR.htmlParser.fragment or CKEDITOR.htmlParser.element. The result of filtering is a DOM tree without disallowed content.

        // Create standalone filter passing 'p' and 'b' elements.
    var filter = new CKEDITOR.filter( 'p b' ),
        // Parse HTML string to pseudo DOM structure.
        fragment = CKEDITOR.htmlParser.fragment.fromHtml( '<p><b>foo</b> <i>bar</i></p>' ),
        writer = new CKEDITOR.htmlParser.basicWriter();
    filter.applyTo( fragment );
    fragment.writeHtml( writer );
    writer.getHtml(); // -> '<p><b>foo</b> bar</p>'


    fragment : fragment | element

    Node to be filtered.

    [ toHtml ] : Boolean

    Set to true if the filter is used together with CKEDITOR.htmlDataProcessor.toHtml.

    [ transformOnly ] : Boolean

    If set to true only transformations will be applied. Content will not be filtered with allowed content rules.

    [ enterMode ] : Number

    Enter mode used by the filter when deciding how to strip disallowed element. Defaults to CKEDITOR.editor.activeEnterMode for a editor's filter or to CKEDITOR.ENTER_P for standalone filter.



    Whether some part of the fragment was removed by the filter.

  • check( test, [ applyTransformations ], [ strictCheck ] ) → Boolean

    Checks whether the content defined in the test argument is allowed by this filter.

    If strictCheck is set to false (default value), this method checks if all parts of the test (styles, attributes, and classes) are accepted by the filter. If strictCheck is set to true, the test must also contain the required attributes, styles, and classes.

    For example:

    // Rule: 'img[!src,alt]'.
    filter.check( 'img[alt]' ); // -> true
    filter.check( 'img[alt]', true, true ); // -> false

    Second check() call returned false because src is required.

    When an array of rules is passed as the test argument, the filter returns true if at least one of the passed rules is allowed.

    For example:

    // Rule: 'img'
    filter.check( [ 'img', 'div' ] ) // -> true
    filter.check( [ 'p', 'div' ] ) // -> false

    Note: The test argument is of CKEDITOR.filter.contentRule type, which is a limited version of CKEDITOR.filter.allowedContentRules. Read more about it in the CKEDITOR.filter.contentRule's documentation.


    test : contentRule | contentRule[]
    [ applyTransformations ] : Boolean

    Whether to use registered transformations.

    Defaults to true

    [ strictCheck ] : Boolean

    Whether the filter should check if an element with exactly these properties is allowed.



    Returns true if the content is allowed.

  • checkFeature( feature ) → Boolean

    Checks whether a CKEDITOR.feature can be enabled. Unlike addFeature, this method always checks the feature, even when the default configuration for CKEDITOR.config.allowedContent is used.

    // TODO example


    feature : feature

    The feature to be tested.



    Whether this feature can be enabled.

  • since 4.7.3

    clone() → filter

    Returns a clone of this filter instance.


  • since 4.4.5


    Destroys the filter instance and removes it from the global instances object.

  • disable()

    Disables Advanced Content Filter.

    This method is meant to be used by plugins which are not compatible with the filter and in other cases in which the filter has to be disabled during the initialization phase or runtime.

    In other cases the filter can be disabled by setting CKEDITOR.config.allowedContent to true.

  • since 4.4.0

    disallow( newRules )

    Adds disallowed content rules to the filter.

    Read about rules formats in the Allowed Content Rules guide.

    // Disallow all styles on the image elements.
    editor.filter.disallow( 'img{*}' );
    // Disallow all span and div elements.
    editor.filter.disallow( 'span div' );


    newRules : disallowedContentRules

    Rule(s) to be added.

  • since 4.3.0

    getAllowedEnterMode( defaultMode, [ reverse ] ) → Number

    Returns first enter mode allowed by this filter rules. Modes are checked in p, div, br order. If none of tags is allowed this method will return CKEDITOR.ENTER_BR.


    defaultMode : Number

    The default mode which will be checked as the first one.

    [ reverse ] : Boolean

    Whether to check modes in reverse order (used for shift enter mode).



    Allowed enter mode.