0
# Element Selection
1

2
Comprehensive element finding and selection methods supporting CSS selectors, XPath, React components, Shadow DOM, and custom selector strategies.
3

4
## Capabilities
5

6
### Browser-Level Element Selection
7

8
Element selection methods available on the browser instance for finding elements in the current page.
9

10
#### Single Element Selection
11

12
Find a single element using various selector strategies.
13

14
```typescript { .api }
15
/**
16
 * Find a single element using CSS selector, XPath, or element function
17
 * @param selector - CSS selector, XPath, or element function
18
 * @returns Promise resolving to the first matching element
19
 */
20
$(selector: Selector): Promise<WebdriverIO.Element>;
21

22
/**
23
 * Find a single element using custom locator strategy
24
 * @param strategy - Custom locator strategy name
25
 * @param selector - Selector string for the custom strategy
26
 * @returns Promise resolving to the first matching element
27
 */
28
custom$(strategy: string, selector: string): Promise<WebdriverIO.Element>;
29

30
/**
31
 * Find a single React component by its component name or props
32
 * @param selector - React component selector (component name or props)
33
 * @returns Promise resolving to the first matching React component element
34
 */
35
react$(selector: string): Promise<WebdriverIO.Element>;
36

37
type Selector = string | Function | object;
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
// CSS selector
44
const button = await browser.$('#submit-btn');
45
const input = await browser.$('input[type="email"]');
46

47
// XPath selector
48
const element = await browser.$('//div[@data-testid="user-profile"]');
49

50
// Element function
51
const dynamicElement = await browser.$(() => {
52
  return document.querySelector('.dynamic-content');
53
});
54

55
// Custom selector strategy
56
const element = await browser.custom$('accessibility id', 'my-button');
57

58
// React component selector
59
const component = await browser.react$('MyComponent');
60
const componentWithProps = await browser.react$('Button[disabled=true]');
61
```
62

63
#### Multiple Element Selection
64

65
Find multiple elements matching the selector criteria.
66

67
```typescript { .api }
68
/**
69
 * Find multiple elements using CSS selector, XPath, or element function
70
 * @param selector - CSS selector, XPath, or element function
71
 * @returns Promise resolving to array of matching elements
72
 */
73
$$(selector: Selector): Promise<WebdriverIO.Element[]>;
74

75
/**
76
 * Find multiple elements using custom locator strategy
77
 * @param strategy - Custom locator strategy name
78
 * @param selector - Selector string for the custom strategy
79
 * @returns Promise resolving to array of matching elements
80
 */
81
custom$$(strategy: string, selector: string): Promise<WebdriverIO.Element[]>;
82

83
/**
84
 * Find multiple React components by their component name or props
85
 * @param selector - React component selector (component name or props)
86
 * @returns Promise resolving to array of matching React component elements
87
 */
88
react$$(selector: string): Promise<WebdriverIO.Element[]>;
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
// Find all list items
95
const listItems = await browser.$$('li.item');
96

97
// Find all buttons with specific attribute
98
const buttons = await browser.$$('button[data-action]');
99

100
// Find multiple React components
101
const allButtons = await browser.react$$('Button');
102

103
// Custom strategy for multiple elements
104
const elements = await browser.custom$$('class name', 'my-class');
105
```
106

107
### Element-Level Element Selection
108

109
Element selection methods available on element instances for finding child elements.
110

111
#### Child Element Selection
112

113
Find child elements within a parent element's scope.
114

115
```typescript { .api }
116
/**
117
 * Find a single child element within this element's scope
118
 * @param selector - CSS selector, XPath, or element function
119
 * @returns Promise resolving to the first matching child element
120
 */
121
$(selector: Selector): Promise<WebdriverIO.Element>;
122

123
/**
124
 * Find multiple child elements within this element's scope
125
 * @param selector - CSS selector, XPath, or element function
126
 * @returns Promise resolving to array of matching child elements
127
 */
128
$$(selector: Selector): Promise<WebdriverIO.Element[]>;
129

130
/**
131
 * Find a single child element using custom locator strategy
132
 * @param strategy - Custom locator strategy name
133
 * @param selector - Selector string for the custom strategy
134
 * @returns Promise resolving to the first matching child element
135
 */
136
custom$(strategy: string, selector: string): Promise<WebdriverIO.Element>;
137

138
/**
139
 * Find multiple child elements using custom locator strategy
140
 * @param strategy - Custom locator strategy name
141
 * @param selector - Selector string for the custom strategy
142
 * @returns Promise resolving to array of matching child elements
143
 */
144
custom$$(strategy: string, selector: string): Promise<WebdriverIO.Element[]>;
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
const form = await browser.$('#user-form');
151

152
// Find child elements within the form
153
const emailInput = await form.$('input[name="email"]');
154
const allInputs = await form.$$('input');
155
const submitButton = await form.$('button[type="submit"]');
156

157
// Chaining element selection
158
const tableRow = await browser.$('table tbody tr:first-child');
159
const firstCell = await tableRow.$('td:first-child');
160
```
161

162
#### React Component Child Selection
163

164
Find React components within a parent element or component.
165

166
```typescript { .api }
167
/**
168
 * Find a single child React component within this element's scope
169
 * @param selector - React component selector (component name or props)
170
 * @returns Promise resolving to the first matching child React component
171
 */
172
react$(selector: string): Promise<WebdriverIO.Element>;
173

174
/**
175
 * Find multiple child React components within this element's scope
176
 * @param selector - React component selector (component name or props)
177
 * @returns Promise resolving to array of matching child React components
178
 */
179
react$$(selector: string): Promise<WebdriverIO.Element[]>;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
const modal = await browser.$('[data-testid="modal"]');
186

187
// Find React components within the modal
188
const closeButton = await modal.react$('CloseButton');
189
const allButtons = await modal.react$$('Button');
190
```
191

192
### Shadow DOM Element Selection
193

194
Methods for selecting elements within Shadow DOM boundaries.
195

196
```typescript { .api }
197
/**
198
 * Find a single element within the Shadow DOM of this element
199
 * @param selector - CSS selector for Shadow DOM element
200
 * @returns Promise resolving to the first matching Shadow DOM element
201
 */
202
shadow$(selector: string): Promise<WebdriverIO.Element>;
203

204
/**
205
 * Find multiple elements within the Shadow DOM of this element
206
 * @param selector - CSS selector for Shadow DOM elements
207
 * @returns Promise resolving to array of matching Shadow DOM elements
208
 */
209
shadow$$(selector: string): Promise<WebdriverIO.Element[]>;
210
```
211

212
**Usage Examples:**
213

214
```typescript
215
// Find element with Shadow DOM
216
const customElement = await browser.$('my-custom-element');
217

218
// Access Shadow DOM children
219
const shadowButton = await customElement.shadow$('button.shadow-btn');
220
const allShadowElements = await customElement.shadow$$('.shadow-content');
221
```
222

223
### Element Navigation
224

225
Methods for navigating between related elements in the DOM tree.
226

227
```typescript { .api }
228
/**
229
 * Get the parent element of this element
230
 * @returns Promise resolving to the parent element
231
 */
232
parentElement(): Promise<WebdriverIO.Element>;
233

234
/**
235
 * Get the next sibling element
236
 * @returns Promise resolving to the next sibling element
237
 */
238
nextElement(): Promise<WebdriverIO.Element>;
239

240
/**
241
 * Get the previous sibling element
242
 * @returns Promise resolving to the previous sibling element
243
 */
244
previousElement(): Promise<WebdriverIO.Element>;
245
```
246

247
**Usage Examples:**
248

249
```typescript
250
const listItem = await browser.$('li.selected');
251

252
// Navigate to related elements
253
const parentList = await listItem.parentElement();
254
const nextItem = await listItem.nextElement();
255
const prevItem = await listItem.previousElement();
256
```
257

258
### Selector Strategies
259

260
WebdriverIO supports multiple selector strategies for maximum flexibility.
261

262
```typescript { .api }
263
const W3C_SELECTOR_STRATEGIES: {
264
  'css selector': string;
265
  'link text': string;
266
  'partial link text': string;
267
  'tag name': string;
268
  'xpath': string;
269
};
270
```
271

272
#### CSS Selectors
273

274
Standard CSS selector syntax with full CSS3 support.
275

276
```typescript
277
// ID selector
278
await browser.$('#my-id');
279

280
// Class selector
281
await browser.$('.my-class');
282

283
// Attribute selectors
284
await browser.$('[data-testid="submit"]');
285
await browser.$('input[type="email"]');
286

287
// Pseudo-selectors
288
await browser.$('tr:first-child');
289
await browser.$('option:checked');
290

291
// Complex selectors
292
await browser.$('form .input-group input[required]');
293
```
294

295
#### XPath Selectors
296

297
XPath expressions for complex element selection logic.
298

299
```typescript
300
// XPath with attributes
301
await browser.$('//button[@data-action="submit"]');
302

303
// XPath with text content
304
await browser.$('//a[contains(text(), "Click here")]');
305

306
// XPath with position
307
await browser.$('//table//tr[2]/td[3]');
308

309
// XPath with multiple conditions
310
await browser.$('//input[@type="text" and @required]');
311
```
312

313
#### Element Functions
314

315
JavaScript functions that return DOM elements for dynamic selection.
316

317
```typescript
318
// Simple element function
319
await browser.$(() => document.getElementById('dynamic-id'));
320

321
// Complex element function with logic
322
await browser.$(() => {
323
  const elements = document.querySelectorAll('.item');
324
  return Array.from(elements).find(el => 
325
    el.textContent.includes('specific text')
326
  );
327
});
328

329
// Element function with parameters
330
const searchTerm = 'example';
331
await browser.$((term) => {
332
  return document.querySelector(`[data-search="${term}"]`);
333
}, searchTerm);
334
```
335

336
#### React Selectors
337

338
Special selectors for React components using the resq library.
339

340
```typescript
341
// Component by name
342
await browser.react$('MyComponent');
343

344
// Component with props
345
await browser.react$('Button[disabled=true]');
346
await browser.react$('Input[type="email"]');
347

348
// Nested component selection
349
await browser.react$('Form').react$('SubmitButton');
350
```