0
# CSS Selection
1

2
CSS selector engine for finding and filtering elements using familiar CSS syntax, plus bulk operations on element collections. jsoup supports the full range of CSS selectors including pseudo-selectors and combinators.
3

4
## Capabilities
5

6
### Element Selection
7

8
Find elements using CSS selectors with comprehensive syntax support.
9

10
```java { .api }
11
/**
12
 * Find descendant elements that match the CSS selector.
13
 * @param cssQuery CSS selector query
14
 * @return Elements collection of matching elements
15
 */
16
public Elements select(String cssQuery);
17

18
/**
19
 * Find the first descendant element that matches the CSS selector.
20
 * @param cssQuery CSS selector query
21
 * @return first matching Element, or null if none found
22
 */
23
public Element selectFirst(String cssQuery);
24

25
/**
26
 * Test if this element matches the CSS selector.
27
 * @param cssQuery CSS selector query
28
 * @return true if element matches selector
29
 */
30
public boolean is(String cssQuery);
31

32
/**
33
 * Find the closest ancestor element that matches the CSS selector.
34
 * @param cssQuery CSS selector query
35
 * @return closest matching ancestor Element, or null if none found
36
 */
37
public Element closest(String cssQuery);
38
```
39

40
**Usage Examples:**
41

42
```java
43
import org.jsoup.Jsoup;
44
import org.jsoup.nodes.Document;
45
import org.jsoup.nodes.Element;
46
import org.jsoup.select.Elements;
47

48
Document doc = Jsoup.parse(html);
49

50
// Basic selectors
51
Elements paragraphs = doc.select("p");
52
Elements divs = doc.select("div");
53
Element firstLink = doc.selectFirst("a");
54

55
// Class and ID selectors
56
Elements highlighted = doc.select(".highlight");
57
Element header = doc.selectFirst("#header");
58
Elements navLinks = doc.select("nav a");
59

60
// Attribute selectors
61
Elements links = doc.select("a[href]");
62
Elements externalLinks = doc.select("a[href^=http]");
63
Elements images = doc.select("img[alt]");
64

65
// Pseudo-selectors
66
Elements firstChildren = doc.select("li:first-child");
67
Elements evenRows = doc.select("tr:nth-child(even)");
68
Elements hasText = doc.select("p:contains(important)");
69
```
70

71
### Advanced CSS Selectors
72

73
jsoup supports the complete CSS selector specification including complex selectors and pseudo-classes.
74

75
**Selector Types:**
76

77
```java
78
// Tag selectors
79
doc.select("p");              // All <p> elements
80
doc.select("div");            // All <div> elements
81

82
// Class selectors  
83
doc.select(".class-name");    // Elements with class="class-name"
84
doc.select("p.highlight");    // <p> elements with class="highlight"
85

86
// ID selectors
87
doc.select("#element-id");    // Element with id="element-id"
88

89
// Attribute selectors
90
doc.select("[href]");         // Elements with href attribute
91
doc.select("[href=value]");   // Elements where href equals "value"
92
doc.select("[href^=http]");   // Elements where href starts with "http"
93
doc.select("[href$=.pdf]");   // Elements where href ends with ".pdf"
94
doc.select("[href*=example]"); // Elements where href contains "example"
95
doc.select("[href~=word]");   // Elements where href contains word "word"
96

97
// Combinators
98
doc.select("div p");          // <p> elements inside <div> (descendant)
99
doc.select("div > p");        // <p> elements directly inside <div> (child)
100
doc.select("h1 + p");         // <p> immediately after <h1> (adjacent sibling)
101
doc.select("h1 ~ p");         // <p> after <h1> at same level (general sibling)
102

103
// Pseudo-selectors
104
doc.select(":first-child");   // First child elements
105
doc.select(":last-child");    // Last child elements
106
doc.select(":nth-child(2n)"); // Even-numbered children
107
doc.select(":nth-child(odd)"); // Odd-numbered children
108
doc.select(":contains(text)"); // Elements containing text
109
doc.select(":matches(regex)"); // Elements matching regex
110
doc.select(":empty");         // Elements with no children
111
doc.select(":has(selector)"); // Elements containing matches for selector
112
```
113

114
**Usage Examples:**
115

116
```java
117
// Complex selectors
118
Elements tableHeaders = doc.select("table tr:first-child th");
119
Elements requiredInputs = doc.select("input[required]");
120
Elements checkedBoxes = doc.select("input[type=checkbox]:checked");
121

122
// Text content selectors
123
Elements warnings = doc.select("p:contains(warning)");
124
Elements phoneNumbers = doc.select("span:matches(\\d{3}-\\d{3}-\\d{4})");
125

126
// Structural selectors
127
Elements oddRows = doc.select("tr:nth-child(odd)");
128
Elements lastItems = doc.select("li:last-child");
129
Elements emptyDivs = doc.select("div:empty");
130

131
// Relational selectors
132
Elements linksInNav = doc.select("nav a");
133
Elements directChildren = doc.select("ul > li");
134
Elements nextSiblings = doc.select("h2 + p");
135
```
136

137
### Elements Collection Operations
138

139
Elements class extends ArrayList<Element> and provides bulk operations on collections of elements.
140

141
```java { .api }
142
/**
143
 * Get the combined text content of all elements.
144
 * @return concatenated text from all elements
145
 */
146
public String text();
147

148
/**
149
 * Get list of text content from each element.
150
 * @return List of text strings
151
 */
152
public List<String> eachText();
153

154
/**
155
 * Test if any element has non-empty text content.
156
 * @return true if any element has text
157
 */
158
public boolean hasText();
159

160
/**
161
 * Get the combined inner HTML of all elements.
162
 * @return concatenated HTML content
163
 */
164
public String html();
165

166
/**
167
 * Set inner HTML content on all elements.
168
 * @param html HTML content to set
169
 * @return this Elements for chaining
170
 */
171
public Elements html(String html);
172

173
/**
174
 * Get the combined outer HTML of all elements.
175
 * @return concatenated outer HTML
176
 */
177
public String outerHtml();
178
```
179

180
**Usage Examples:**
181

182
```java
183
Elements paragraphs = doc.select("p");
184

185
// Text operations
186
String allText = paragraphs.text();
187
List<String> individualTexts = paragraphs.eachText();
188
boolean hasAnyText = paragraphs.hasText();
189

190
// HTML operations
191
String combinedHtml = paragraphs.html();
192
paragraphs.html("<strong>New content</strong>");
193
String outerHtml = paragraphs.outerHtml();
194
```
195

196
### Bulk Attribute Operations
197

198
Perform attribute operations on all elements in a collection.
199

200
```java { .api }
201
/**
202
 * Get attribute value from the first element.
203
 * @param attributeKey attribute name
204
 * @return attribute value from first element
205
 */
206
public String attr(String attributeKey);
207

208
/**
209
 * Set attribute on all elements.
210
 * @param attributeKey attribute name
211
 * @param attributeValue attribute value
212
 * @return this Elements for chaining
213
 */
214
public Elements attr(String attributeKey, String attributeValue);
215

216
/**
217
 * Get list of attribute values from all elements.
218
 * @param attributeKey attribute name
219
 * @return List of attribute values
220
 */
221
public List<String> eachAttr(String attributeKey);
222

223
/**
224
 * Test if any element has the specified attribute.
225
 * @param attributeKey attribute name
226
 * @return true if any element has the attribute
227
 */
228
public boolean hasAttr(String attributeKey);
229

230
/**
231
 * Remove attribute from all elements.
232
 * @param attributeKey attribute name to remove
233
 * @return this Elements for chaining
234
 */
235
public Elements removeAttr(String attributeKey);
236
```
237

238
**Usage Examples:**
239

240
```java
241
Elements links = doc.select("a");
242

243
// Attribute operations
244
String firstHref = links.attr("href");
245
links.attr("target", "_blank");  // Set on all links
246
List<String> allHrefs = links.eachAttr("href");
247
links.removeAttr("title");
248

249
// Check for attributes
250
boolean anyHasClass = links.hasAttr("class");
251
```
252

253
### Bulk CSS Class Operations
254

255
Manipulate CSS classes on all elements in a collection.
256

257
```java { .api }
258
/**
259
 * Add CSS class to all elements.
260
 * @param className class name to add
261
 * @return this Elements for chaining
262
 */
263
public Elements addClass(String className);
264

265
/**
266
 * Remove CSS class from all elements.
267
 * @param className class name to remove
268
 * @return this Elements for chaining
269
 */
270
public Elements removeClass(String className);
271

272
/**
273
 * Toggle CSS class on all elements.
274
 * @param className class name to toggle
275
 * @return this Elements for chaining
276
 */
277
public Elements toggleClass(String className);
278

279
/**
280
 * Test if any element has the specified CSS class.
281
 * @param className class name to test
282
 * @return true if any element has the class
283
 */
284
public boolean hasClass(String className);
285
```
286

287
**Usage Examples:**
288

289
```java
290
Elements buttons = doc.select("button");
291

292
// Class operations
293
buttons.addClass("btn");
294
buttons.addClass("btn-primary");
295
buttons.removeClass("disabled");
296
buttons.toggleClass("active");
297

298
boolean anyActive = buttons.hasClass("active");
299
```
300

301
### Bulk Form Operations
302

303
Work with form element values across collections.
304

305
```java { .api }
306
/**
307
 * Get form value from the first element.
308
 * @return form value from first element
309
 */
310
public String val();
311

312
/**
313
 * Set form value on all elements.
314
 * @param value new form value
315
 * @return this Elements for chaining
316
 */
317
public Elements val(String value);
318
```
319

320
**Usage Examples:**
321

322
```java
323
Elements textInputs = doc.select("input[type=text]");
324
Elements checkboxes = doc.select("input[type=checkbox]");
325

326
// Form operations
327
String firstValue = textInputs.val();
328
textInputs.val("");  // Clear all text inputs
329
checkboxes.val("checked");  // Check all checkboxes
330
```
331

332
### Collection Filtering and Traversal
333

334
Further filter and navigate element collections.
335

336
```java { .api }
337
/**
338
 * Find elements within this collection that match the selector.
339
 * @param cssQuery CSS selector
340
 * @return Elements collection of matches
341
 */
342
public Elements select(String cssQuery);
343

344
/**
345
 * Find first element in collection that matches the selector.
346
 * @param cssQuery CSS selector
347
 * @return first matching Element, or null if none
348
 */
349
public Element selectFirst(String cssQuery);
350

351
/**
352
 * Remove elements from this collection that match the selector.
353
 * @param cssQuery CSS selector
354
 * @return this Elements with matching elements removed
355
 */
356
public Elements not(String cssQuery);
357

358
/**
359
 * Test if any element in collection matches the selector.
360
 * @param cssQuery CSS selector
361
 * @return true if any element matches
362
 */
363
public boolean is(String cssQuery);
364

365
/**
366
 * Get element at specified index as single-element collection.
367
 * @param index zero-based index
368
 * @return Elements containing element at index
369
 */
370
public Elements eq(int index);
371

372
/**
373
 * Get first element as single-element collection.
374
 * @return Elements containing first element
375
 */
376
public Elements first();
377

378
/**
379
 * Get last element as single-element collection.
380
 * @return Elements containing last element
381
 */
382
public Elements last();
383
```
384

385
**Usage Examples:**
386

387
```java
388
Elements allLinks = doc.select("a");
389

390
// Further filtering
391
Elements externalLinks = allLinks.select("[href^=http]");
392
Elements internalLinks = allLinks.not("[href^=http]");
393
Element firstExternal = allLinks.selectFirst("[href^=http]");
394

395
// Collection operations
396
Elements firstLink = allLinks.first();
397
Elements lastLink = allLinks.last();
398
Elements thirdLink = allLinks.eq(2);
399

400
// Testing
401
boolean hasExternal = allLinks.is("[href^=http]");
402
```
403

404
### Sibling Navigation
405

406
Navigate to sibling elements from a collection.
407

408
```java { .api }
409
/**
410
 * Get immediate next sibling elements.
411
 * @return Elements collection of next siblings
412
 */
413
public Elements next();
414

415
/**
416
 * Get filtered immediate next sibling elements.
417
 * @param cssQuery CSS selector filter
418
 * @return Elements collection of matching next siblings
419
 */
420
public Elements next(String cssQuery);
421

422
/**
423
 * Get all following sibling elements.
424
 * @return Elements collection of following siblings
425
 */
426
public Elements nextAll();
427

428
/**
429
 * Get filtered following sibling elements.
430
 * @param cssQuery CSS selector filter
431
 * @return Elements collection of matching following siblings
432
 */
433
public Elements nextAll(String cssQuery);
434

435
/**
436
 * Get immediate previous sibling elements.
437
 * @return Elements collection of previous siblings
438
 */
439
public Elements prev();
440

441
/**
442
 * Get filtered immediate previous sibling elements.
443
 * @param cssQuery CSS selector filter
444
 * @return Elements collection of matching previous siblings
445
 */
446
public Elements prev(String cssQuery);
447

448
/**
449
 * Get all previous sibling elements.
450
 * @return Elements collection of previous siblings
451
 */
452
public Elements prevAll();
453

454
/**
455
 * Get filtered previous sibling elements.
456
 * @param cssQuery CSS selector filter
457
 * @return Elements collection of matching previous siblings
458
 */
459
public Elements prevAll(String cssQuery);
460
```
461

462
**Usage Examples:**
463

464
```java
465
Elements listItems = doc.select("li");
466

467
// Sibling navigation
468
Elements nextItems = listItems.next();
469
Elements nextHeaders = listItems.next("h2, h3");
470
Elements allFollowing = listItems.nextAll();
471
Elements previousItems = listItems.prev();
472
Elements allPrevious = listItems.prevAll();
473
```
474

475
### Parent Navigation
476

477
Navigate to parent elements from a collection.
478

479
```java { .api }
480
/**
481
 * Get parent elements.
482
 * @return Elements collection of parent elements
483
 */
484
public Elements parents();
485
```
486

487
**Usage Example:**
488

489
```java
490
Elements spans = doc.select("span.highlight");
491
Elements parentElements = spans.parents();
492
Elements parentDivs = spans.parents().select("div");
493
```
494

495
### Bulk DOM Modification
496

497
Modify DOM structure for all elements in a collection.
498

499
```java { .api }
500
/**
501
 * Parse and append HTML to all elements.
502
 * @param html HTML to append
503
 * @return this Elements for chaining
504
 */
505
public Elements append(String html);
506

507
/**
508
 * Parse and prepend HTML to all elements.
509
 * @param html HTML to prepend
510
 * @return this Elements for chaining
511
 */
512
public Elements prepend(String html);
513

514
/**
515
 * Insert HTML before all elements.
516
 * @param html HTML to insert
517
 * @return this Elements for chaining
518
 */
519
public Elements before(String html);
520

521
/**
522
 * Insert HTML after all elements.
523
 * @param html HTML to insert
524
 * @return this Elements for chaining
525
 */
526
public Elements after(String html);
527

528
/**
529
 * Wrap all elements with HTML.
530
 * @param html HTML to wrap with
531
 * @return this Elements for chaining
532
 */
533
public Elements wrap(String html);
534

535
/**
536
 * Remove wrapper elements but keep their children.
537
 * @return this Elements for chaining
538
 */
539
public Elements unwrap();
540

541
/**
542
 * Remove all child nodes from all elements.
543
 * @return this Elements for chaining
544
 */
545
public Elements empty();
546

547
/**
548
 * Remove all elements from the DOM.
549
 * @return this Elements for chaining
550
 */
551
public Elements remove();
552
```
553

554
**Usage Examples:**
555

556
```java
557
Elements paragraphs = doc.select("p");
558

559
// Bulk modifications
560
paragraphs.addClass("paragraph");
561
paragraphs.append("<span class='marker'>*</span>");
562
paragraphs.wrap("<div class='content'></div>");
563

564
// Remove elements
565
Elements ads = doc.select(".advertisement");
566
ads.remove();
567

568
// Clear content
569
Elements containers = doc.select(".container");
570
containers.empty();
571
```
572

573
### Specialized Collections
574

575
Extract specific types of nodes from element collections.
576

577
```java { .api }
578
/**
579
 * Get FormElement forms from the selection.
580
 * @return Elements collection containing forms
581
 */
582
public Elements forms();
583

584
/**
585
 * Get Comment nodes from element descendants.
586
 * @return List of Comment nodes
587
 */
588
public List<Comment> comments();
589

590
/**
591
 * Get TextNode nodes from element descendants.
592
 * @return List of TextNode nodes
593
 */
594
public List<TextNode> textNodes();
595

596
/**
597
 * Get DataNode nodes from element descendants.
598
 * @return List of DataNode nodes
599
 */
600
public List<DataNode> dataNodes();
601
```
602

603
**Usage Examples:**
604

605
```java
606
Elements divs = doc.select("div");
607

608
// Get specialized collections
609
Elements forms = divs.forms();
610
List<Comment> comments = divs.comments();
611
List<TextNode> textNodes = divs.textNodes();
612
List<DataNode> scriptData = doc.select("script").dataNodes();
613

614
// Work with text nodes
615
for (TextNode textNode : textNodes) {
616
    String text = textNode.text();
617
    if (text.trim().isEmpty()) {
618
        textNode.remove();  // Remove empty text nodes
619
    }
620
}
621
```
622

623
This comprehensive CSS selection API provides powerful, jQuery-like capabilities for finding, filtering, and manipulating HTML elements using familiar CSS selector syntax.