--- title: "CSS Selector Extractor" description: "Configure the JMeter CSS Selector Extractor post-processors: properties, defaults, and practical usage notes for building reliable load tests." url: https://docs.jmeter.ai/components/css-selector-extractor/ lastUpdated: 2026-10-01 source: docs.jmeter.ai --- # CSS Selector Extractor *Part of the **Post-Processors** category — formerly called **CSS/JQuery Extractor**. Also documented in context in the [full Component Reference](/user-manual/component-reference/#css-selector-extractor).* ![CSS Selector Extractor](/images/screenshots/css_extractor_attr.png) Allows the user to extract values from a server HTML response using a CSS Selector syntax. As a post-processor, this element will execute after each Sample request in its scope, applying the CSS/JQuery expression, extracting the requested nodes, extracting the node as text or attribute value and store the result into the given variable name. | Name | Required | Description | | --- | --- | --- | | Name | No | Descriptive name for this element that is shown in the tree. | | Apply to: | Yes | This is for use with samplers that can generate sub-samples, e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller. - `Main sample only` - only applies to the main sample - `Sub-samples only` - only applies to the sub-samples - `Main sample and sub-samples` - applies to both. - `JMeter Variable Name to use` - extraction is to be applied to the contents of the named variable Matching is applied to all qualifying samples in turn. For example if there is a main sample and 3 sub-samples, each of which contains a single match for the regex, (i.e. 4 matches in total). For match number = `3`, Sub-samples only, the extractor will match the 3rd sub-sample. For match number = `3`, Main sample and sub-samples, the extractor will match the 2nd sub-sample (1st match is main sample). For match number = `0` or negative, all qualifying samples will be processed. For match number > `0`, matching will stop as soon as enough matches have been found. | | CSS Selector Implementation | False | 2 Implementations for CSS/JQuery based syntax are supported: - [JSoup](http://jsoup.org/) - [Jodd-Lagarto (CSSelly)](http://jodd.org/doc/lagarto/index.html) If selector is set to empty, default implementation(JSoup) will be used. | | Name of created variable | Yes | The name of the JMeter variable in which to store the result. | | CSS/JQuery expression | Yes | The CSS/JQuery selector used to select nodes from the response data. Selector, selectors combination and pseudo-selectors are supported, examples: - `E[foo]` - an `E` element with a “`foo`” attribute - `ancestor child` - child elements that descend from ancestor, e.g. `.body p` finds `p` elements anywhere under a block with class “`body`” - `:lt(n)` - find elements whose sibling index (i.e. its position in the DOM tree relative to its parent) is less than `n`; e.g. `td:lt(3)` - `:contains(text)` - find elements that contain the given `text`. The search is case-insensitive; e.g. `p:contains(jsoup)` - … For more details on syntax, see: - [JSoup](http://jsoup.org/cookbook/extracting-data/selector-syntax) - [Jodd-Lagarto (CSSelly)](http://jodd.org/doc/csselly/) | | Attribute | false | Name of attribute (as per HTML syntax) to extract from nodes that matched the selector. If empty, then the combined text of this element and all its children will be returned. This is the equivalent [Element#attr(name)](http://jsoup.org/apidocs/org/jsoup/nodes/Node.html#attr%28java.lang.String%29) function for JSoup if an attribute is set. ![CSS Extractor with attribute value set](/images/screenshots/css_extractor_attr.png) *CSS Extractor with attribute value set* If empty this is the equivalent of [Element#text()](http://jsoup.org/apidocs/org/jsoup/nodes/Element.html#text%28%29) function for JSoup if not value is set for attribute. ![CSS Extractor with no attribute set](/images/screenshots/css_extractor_noattr.png) *CSS Extractor with no attribute set* | | Match No. (0 for Random) | Yes | Indicates which match to use. The CSS/JQuery selector may match multiple times. - Use a value of zero to indicate JMeter should choose a match at random. - A positive number `N` means to select the nth match. - Negative numbers are used in conjunction with the [ForEach Controller](/components/foreach-controller/) - see below. | | Default Value | No, but recommended | If the expression does not match, then the reference variable will be set to the default value. This is particularly useful for debugging tests. If no default is provided, then it is difficult to tell whether the expression did not match, or the CSS/JQuery element was not processed or maybe the wrong variable is being used. However, if you have several test elements that set the same variable, you may wish to leave the variable unchanged if the expression does not match. In this case, remove the default value once debugging is complete. | | Use empty default value | No | If the checkbox is checked and `Default Value` is empty, then JMeter will set the variable to empty string instead of not setting it. Thus when you will for example use `\${var}` (if `Reference Name` is var) in your Test Plan, if the extracted value is not found then `\${var}` will be equal to empty string instead of containing `\${var}` which may be useful if extracted value is optional. | If the match number is set to a non-negative number, and a match occurs, the variables are set as follows: - `refName` - the value of the template If no match occurs, then the `refName` variable is set to the default (unless this is absent). If the match number is set to a negative number, then all the possible matches in the sampler data are processed. The variables are set as follows: - `refName_matchNr` - the number of matches found; could be `0` - `refName_n`, where `n` = `1`, `2`, `3`, etc. - the strings as generated by the template - `refName` - always set to the default value Note that the `refName` variable is always set to the default value in this case. ## Related - [Correlation & Dynamic Values](/topics/correlation-dynamic-values/) - [Regex Extractor Builder](/tools/regex-tester/) - [Full Component Reference](/user-manual/component-reference/) - [Functions and Variables](/user-manual/functions/)