Skip to content

How-to Guides

Technical References

Security /

JavaScript security recommendations

The primary vulnerability of note in JavaScript is Cross Site Scripting (XSS). In WordPress with PHP, best practice is to use escaping functions to avoid that, e.g. esc_html(), esc_attr(), esc_url(), etc.

However, that’s the wrong way to approach JavaScript security. To avoid XSS, you should avoid inserting HTML directly into the document and instead, programmatically create DOM nodes and append them to the DOM. This means avoiding .html(), .innerHTML, and other related functions, and instead using .append(), .prepend(), .before(), .after(), and so on.

Here is an example:

jQuery.ajax({
    url: 'http://any-site.com/endpoint.json'
}).done( function( data ) {
    var link = '<a href="' + data.url + '">' + data.title + '</a>';

    jQuery( '#my-div' ).html( link );
});

This approach is dangerous, because it assumes that the response from any-site.com includes only safe data – something we can not guarantee, even if the site is our own.

Instead, the correct approach is to create a new DOM node programmatically, then attach it to the DOM:

jQuery.ajax({
    url: 'http://any-site.com/endpoint.json'
}).done( function( data ) {
    var a = jQuery( '<a />' );
    a.attr( 'href', data.url );
    a.text( data.title );

    jQuery( '#my-div' ).append( a );
});

Pro Tip

It’s technically faster to insert HTML, because the browser is optimized to parse HTML. The best solution is to minimize insertions of DOM nodes by building larger objects in memory, then insert it into the DOM all at once, when possible.

By passing the data through either jQuery or the browser’s DOM API’s, we ensure the values are properly sanitized and remove the need to inject insecure HTML snippets into the page.

To ensure the security of your application, use the DOM APIs provided by the browser (or jQuery) for all DOM manipulation.

Escaping dynamic JavaScript values

When it comes to sending dynamic data from PHP to JavaScript, it’s important to ensure values are properly escaped. The core function esc_js() helps escape JavaScript for us in DOM attributes, while all other values should be encoded with json_encode().

WordPress Reference

It is intended to be used for inline JS (in a tag attribute, for example onclick=”…”).

If you’re not working with inline JS in HTML event handler attributes, a more suitable function to use is json_encode, which is built-in to PHP.

—From the WP Codex on esc_js()

This approach is incorrect:

var title = '<?php echo esc_js( $title ); ?>';
var url = '<?php echo esc_js( $url ); ?>';

Depending on the context, it’s better to use rawurlencode() (note that it adds the quotes automatically) or wp_json_encode() in combination with esc_url():

var title = decodeURIComponent( '<?php echo rawurlencode( (string) $title ); ?>' );
var url   = <?php echo wp_json_encode( esc_url( $url ) ) ?>;

For more examples, please see our code sample repository.

Stripping tags

It may be tempting to use .html() followed by .text() to strip tags – but this approach is still vulnerable to attack:

// Incorrect
var text = jQuery('<div />').html( some_html_string ).text();
jQuery( '.some-div' ).html( text );

Setting the HTML of an element will always trigger things like src attributes to be executed, which can lead to attacks like this:

// XSS attack waiting to happen.
var some_html_string = '<img src="a" onerror="alert(\'haxxored\');" />';

As soon as that string is set as a DOM element’s HTML (even if it’s not currently attached to the DOM), src will be loaded, will error out, and the code in the onerror handler will be executed, all before .text() is ever called.

The need to strip tags is often indicative of bad practices — remember, always use the appropriate API for DOM manipulation.

// Correct
jQuery( '.some-div' ).text( some_html_string );

Here are some things to watch out for:

// jQuery passes the values in these methods through to eval():
$('#my-div').after('<script>alert("1. XSS Attack with jQuery after()");</script>');
$('#my-div').append('<script>alert("2. XSS Attack with jQuery append()");</script>');
$('#my-div').before('<script>alert("3. XSS Attack with jQuery before()");</script>');
$('#my-div').html('<script>alert("4. XSS Attack with jQuery html()");</script>');
$('#my-div').prepend('<script>alert("5. XSS Attack with jQuery prepend()");</script>');
$('#my-div').replaceWith('<div id="my-div"><script>alert("6. XSS Attack with jQuery replaceWith()");</script></div>');


// And these:
$('<script>alert("7. XSS Attack with jQuery appendTo()");</script>').appendTo('#my-div');
$('<script>alert("8. XSS Attack with jQuery insertAfter()");</script>').insertAfter('#my-div');
$('<script>alert("9. XSS Attack with jQuery insertBefore()");</script>').insertBefore('#my-div');
$('<script>alert("10. XSS Attack with jQuery prependTo()");</script>').prependTo('#my-div');
$('<div id="my-div"><script>alert("11. XSS Attack with jQuery replaceAll()");</script></div>').replaceAll('#my-div');


// Plain JS will also evaluate these:
document.write('<script>alert("12. XSS Attack with document.write()");</script>');
document.writeln('<script>alert("13. XSS Attack with document.writeln()");</script>');


// Script elements inserted using innerHTML do not execute when they are inserted: https://www.w3.org/TR/2008/WD-html5-20080610/dom.html#innerhtml0
var div = document.createElement('div');
document.body.append(div);

div.innerHTML = 'Foo<script>alert("No attack with script innerHTML");</script>';
div.innerHTML = 'Foo<span></span><script defer>alert("No attack with deferred script innerHTML");</script>';
div.innerHTML = '<scr' + 'ipt>alert("No attack with concat script tag innerHTML");</script>';


// JS prepend() and JS append() are safe when using strings:
var div2 = document.createElement('div');
document.body.append(div2);

div2.prepend('<script>alert("No attack with JS prepend()");</script>');
div2.append('<script>alert("No attack with JS append()");</script>');


// ...But not safe when inserting a Node:
var div3 = document.createElement('div');
document.body.append(div3);

var newScript = document.createElement("script");
var inlineScript = document.createTextNode("alert('14. XSS Attack with JS append()');");
newScript.append(inlineScript);
div3.append(newScript);


// Other ways to use innerHTML can cause XSS though:
var div4 = document.createElement('div');
document.body.append(div4);

var myImageSrc = 'x" onerror="alert(\'15. XSS Attack with img innerHTML\')';
div.innerHTML = '<img src="' + myImageSrc + '">';

You can run this JSBin to see it in action.

Using encodeURIComponent()

When using values as part of a URL, for example when adding parameters to a URL or building a mailto: link, the JavaScript variables need to be encoded to be correctly interpreted by the browser. Using encodeURIComponent() will ensure that the characters you use will be properly interpreted by the browser. This also helps prevent some trickery such as adding & which may cause the browser to incorrectly interpret the values you were expecting. You can find more information on this on the OWASP website.

Using DOMPurify

As mentioned above, using jQuery’s .html() function or React’s dangerouslySetInnerHTML() function can open your site to XSS vulnerabilities by treating arbitrary strings as HTML. These functions should be avoided whenever possible. While it’s easy to think content from your own site is “safe,” it can become an attack vector if a user’s account is compromised or if another part of the application is not doing enough validation.

While we recommend that first you try to use structured data and build the HTML inside the JavaScript, that’s not always feasible. If you do need to include HTML strings inside your JavaScript, we recommend using the DOMPurify package to sanitize strings to remove executable elements that could contain attack vectors. This is very similar to how WP_KSES works.

To use DOMPurify you need to include as follows:

/**
 * For Browsers
 */
import DOMPurify from 'dompurify';
// or
const DOMPurify = require('dompurify');

/**
 * For Node.js we need JSDOM's window
 */
const createDOMPurify = require('dompurify');
const { JSDOM } = require('jsdom'); 
const window = (new JSDOM('')).window;
const DOMPurify = createDOMPurify(window);

You can then call it something like:

const clean = DOMPurify.sanitize(dirty);

Here are a few examples taken from the DOMPurify Readme:

DOMPurify.sanitize('<img src=x onerror=alert(1)//>'); // becomes <img src="x">
DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>'); // becomes <svg><g></g></svg>
DOMPurify.sanitize('<p>abc<iframe//src=jAva	script:alert(3)>def</p>'); // becomes <p>abcdef</p>
DOMPurify.sanitize('<math><mi//xlink:href="data:x,<script>alert(4)</script>">'); // becomes <math><mi></mi></math>
DOMPurify.sanitize('<TABLE><tr><td>HELLO</tr></TABL>'); // becomes <table><tbody><tr><td>HELLO</td></tr></tbody></table>
DOMPurify.sanitize('<UL><li><A HREF=//google.com>click</UL>'); // becomes <ul><li><a href="//google.com">click</a></li></ul>

Other common XSS vectors

  • Using eval(). Never do this.
  • Un-safelisted / un-sanitized data from URLs, URL fragments, query strings, cookies
  • Including untrusted / unreviewed third-party JavaScript libraries
  • Using outdated / unpatched third-party JavaScript libraries

Helpful resources

OWASP XSS Prevention Cheat Sheet

Google on Cross Site Scripting

Last updated: November 24, 2020