jQuery jQuery.escapeSelector() Method

What You’ll Learn

The jQuery.escapeSelector() utility escapes CSS special characters in a string so you can safely splice it into jQuery selector expressions. This tutorial covers syntax, the official jQuery API example, selecting elements with literal dots or hashes in class and id names, comparisons with CSS.escape() and attribute selectors, and building dynamic selectors from user input.

Introduction

CSS selectors treat certain characters as syntax. A dot means “class,” a hash means “id,” brackets introduce attribute filters, and colons start pseudo-classes. That works perfectly until an element’s actual class or id attribute value contains one of those characters — for example class=".box" or id="#list".

jQuery added jQuery.escapeSelector() (also written $.escapeSelector()) in version 3.0 so developers can escape identifier strings before concatenating them into selectors like "." + escaped or "#" + escaped. Without escaping, $(".box") finds elements with class box, not the rare but real case where the class name is literally .box.

Understanding the jQuery.escapeSelector() Method

jQuery.escapeSelector(selector) accepts one string argument and returns a new string with backslash escapes inserted wherever CSS would otherwise interpret a character as selector syntax. The result is meant to be embedded inside a larger selector — you still add the leading . for classes or # for ids yourself.

This is a static utility on the jQuery namespace, not a method you call on a collection. It does not query the DOM; it only prepares text. Common special characters that get escaped include #, ., [, ], :, spaces, and other punctuation that Sizzle would parse as operators.

📝 Syntax

General form of jQuery.escapeSelector:

jQuery.escapeSelector( selector )
// or
$.escapeSelector( selector )

Parameters

• selector — a string representing part of a CSS identifier (a class name, id value, or similar fragment) that may contain special characters.

Return value

• A string with special CSS characters escaped so it can be safely concatenated into a jQuery selector.
• The original string is not modified; a new escaped copy is returned.

Official jQuery API example

$.escapeSelector( "#target" );
// "\#target"

Examples Gallery

Each example uses $.escapeSelector(). Open DevTools or use the Try-it links. Example 1 matches the official jQuery API documentation.

var escaped = $.escapeSelector("#target");

console.log(escaped);
// "\#target"

// Use when the element's id attribute is literally "#target":
// $("#" + $.escapeSelector("#target"))

\#target

// HTML includes:
// <div class="box">Normal</div>
// <div class=".box">Literal dot-box</div>

$("div").removeClass("highlight");

// Match class=".box" only — not class="box"
$("." + $.escapeSelector(".box")).addClass("highlight");

1 element highlighted (class=".box")

// <li class="list">Plain "list"</li>
// <li class=".list">Literal ".list"</li>

$("li").removeClass("highlight");

$("." + $.escapeSelector(".list")).addClass("highlight");

console.log("Matched", $("." + $.escapeSelector(".list")).length, "element(s)");

Matched 1 element(s)

// <li id="list">Normal id</li>
// <li id="#list">Literal hash id</li>

$("li").removeClass("highlight");

$("#" + $.escapeSelector("#list")).addClass("highlight");

console.log("Highlighted id:", $("#" + $.escapeSelector("#list")).attr("id"));

Highlighted id: #list

function findByClassName(name) {
  var safeSelector = "." + $.escapeSelector(name);
  console.log("Built selector:", safeSelector);
  $(".tag").removeClass("match");
  $(safeSelector).addClass("match");
  return $(safeSelector).length;
}

// User types "item.main" — dots are escaped automatically
findByClassName("item.main"); // Built selector: .item\.main

Built selector: .item\.main
1 match

🚀 Common Use Cases

• CMS-generated class names — frameworks sometimes emit classes with dots, colons, or brackets that break naive $("." + name) concatenation.
• Widget configuration — escape id or class values read from data-* attributes before querying child elements.
• Search / filter UIs — highlight tags or categories when users pick labels containing special characters.
• Legacy markup — support HTML where ids or classes were copied from CSS selectors literally, including leading # or ..
• Plugin development — accept arbitrary class hooks from consumers without documenting “avoid dots” restrictions.
• Testing & debugging — verify Sizzle matches the same elements as attribute-based queries on oddball identifiers.

📝 Notes

• Available since jQuery 3.0; still supported in current 3.x — not deprecated.
• Static utility only: $.escapeSelector(str) — there is no .escapeSelector() on collections.
• You must still add the combinator (. or #) when building class or id selectors.
• For exact attribute matching, [class="value"] or [id="value"] can work but require careful quoting of quotes inside values.
• Native CSS.escape() escapes identifiers for CSS contexts; behavior is similar but not identical to Sizzle’s expectations in every edge case.
• Escaping does not validate that the selector exists in the DOM — it only makes the syntax safe.

💡 Best Practices