0
# DOM Queries
1

2
Complete set of Testing Library query functions for finding elements in the DOM. All queries are instrumented for Storybook interaction tracking and follow the Testing Library query pattern: getBy* (throw error), getAllBy* (throw error, return array), queryBy* (return null), queryAllBy* (return empty array), findBy* (async, reject), findAllBy* (async, reject, return array).
3

4
## Capabilities
5

6
### getBy* Queries
7

8
Synchronous queries that throw an error if no matching element is found. Use these when you expect the element to exist.
9

10
```typescript { .api }
11
/**
12
 * Find element by ARIA role
13
 * @param container - Container element to search within
14
 * @param role - ARIA role to search for
15
 * @param options - Additional options for role matching
16
 * @returns Single matching element
17
 * @throws Error if no element found or multiple elements found
18
 */
19
function getByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement;
20

21
/**
22
 * Find element by text content
23
 * @param container - Container element to search within  
24
 * @param text - Text content to search for (string or regex)
25
 * @param options - Text matching options
26
 * @returns Single matching element
27
 * @throws Error if no element found or multiple elements found
28
 */
29
function getByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;
30

31
/**
32
 * Find element by test-id attribute
33
 * @param container - Container element to search within
34
 * @param testId - Test ID attribute value to search for
35
 * @param options - Text matching options
36
 * @returns Single matching element
37
 * @throws Error if no element found or multiple elements found
38
 */
39
function getByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement;
40

41
/**
42
 * Find element by label text
43
 * @param container - Container element to search within
44
 * @param text - Label text to search for (string or regex)
45
 * @param options - Text matching options
46
 * @returns Single matching element
47
 * @throws Error if no element found or multiple elements found
48
 */
49
function getByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;
50

51
/**
52
 * Find element by placeholder text
53
 * @param container - Container element to search within
54
 * @param text - Placeholder text to search for (string or regex)
55
 * @param options - Text matching options
56
 * @returns Single matching element
57
 * @throws Error if no element found or multiple elements found
58
 */
59
function getByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;
60

61
/**
62
 * Find element by alt attribute
63
 * @param container - Container element to search within
64
 * @param text - Alt text to search for (string or regex)
65
 * @param options - Text matching options
66
 * @returns Single matching element
67
 * @throws Error if no element found or multiple elements found
68
 */
69
function getByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;
70

71
/**
72
 * Find element by title attribute
73
 * @param container - Container element to search within
74
 * @param text - Title text to search for (string or regex)
75
 * @param options - Text matching options
76
 * @returns Single matching element
77
 * @throws Error if no element found or multiple elements found
78
 */
79
function getByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;
80

81
/**
82
 * Find form element by display value
83
 * @param container - Container element to search within
84
 * @param value - Display value to search for (string or regex)
85
 * @param options - Text matching options
86
 * @returns Single matching element
87
 * @throws Error if no element found or multiple elements found
88
 */
89
function getByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;
90
```
91

92
### getAllBy* Queries
93

94
Synchronous queries that return an array of all matching elements. Throw an error if no elements are found.
95

96
```typescript { .api }
97
/**
98
 * Find all elements by ARIA role
99
 * @param container - Container element to search within
100
 * @param role - ARIA role to search for
101
 * @param options - Additional options for role matching
102
 * @returns Array of matching elements
103
 * @throws Error if no elements found
104
 */
105
function getAllByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement[];
106

107
/**
108
 * Find all elements by text content
109
 * @param container - Container element to search within
110
 * @param text - Text content to search for (string or regex)
111
 * @param options - Text matching options
112
 * @returns Array of matching elements
113
 * @throws Error if no elements found
114
 */
115
function getAllByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
116

117
/**
118
 * Find all elements by test-id attribute
119
 * @param container - Container element to search within
120
 * @param testId - Test ID attribute value to search for
121
 * @param options - Text matching options
122
 * @returns Array of matching elements
123
 * @throws Error if no elements found
124
 */
125
function getAllByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement[];
126

127
/**
128
 * Find all elements by label text
129
 * @param container - Container element to search within
130
 * @param text - Label text to search for (string or regex)
131
 * @param options - Text matching options
132
 * @returns Array of matching elements
133
 * @throws Error if no elements found
134
 */
135
function getAllByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
136

137
/**
138
 * Find all elements by placeholder text
139
 * @param container - Container element to search within
140
 * @param text - Placeholder text to search for (string or regex)
141
 * @param options - Text matching options
142
 * @returns Array of matching elements
143
 * @throws Error if no elements found
144
 */
145
function getAllByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
146

147
/**
148
 * Find all elements by alt attribute
149
 * @param container - Container element to search within
150
 * @param text - Alt text to search for (string or regex)
151
 * @param options - Text matching options
152
 * @returns Array of matching elements
153
 * @throws Error if no elements found
154
 */
155
function getAllByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
156

157
/**
158
 * Find all elements by title attribute
159
 * @param container - Container element to search within
160
 * @param text - Title text to search for (string or regex)
161
 * @param options - Text matching options
162
 * @returns Array of matching elements
163
 * @throws Error if no elements found
164
 */
165
function getAllByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
166

167
/**
168
 * Find all form elements by display value
169
 * @param container - Container element to search within
170
 * @param value - Display value to search for (string or regex)
171
 * @param options - Text matching options
172
 * @returns Array of matching elements
173
 * @throws Error if no elements found
174
 */
175
function getAllByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
176
```
177

178
### queryBy* Queries
179

180
Synchronous queries that return null if no matching element is found. Use these for optional elements or when you want to check if an element doesn't exist.
181

182
```typescript { .api }
183
/**
184
 * Query element by ARIA role
185
 * @param container - Container element to search within
186
 * @param role - ARIA role to search for
187
 * @param options - Additional options for role matching
188
 * @returns Single matching element or null if not found
189
 */
190
function queryByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement | null;
191

192
/**
193
 * Query element by text content
194
 * @param container - Container element to search within
195
 * @param text - Text content to search for (string or regex)
196
 * @param options - Text matching options
197
 * @returns Single matching element or null if not found
198
 */
199
function queryByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;
200

201
/**
202
 * Query element by test-id attribute
203
 * @param container - Container element to search within
204
 * @param testId - Test ID attribute value to search for
205
 * @param options - Text matching options
206
 * @returns Single matching element or null if not found
207
 */
208
function queryByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement | null;
209

210
/**
211
 * Query element by label text
212
 * @param container - Container element to search within
213
 * @param text - Label text to search for (string or regex)
214
 * @param options - Text matching options
215
 * @returns Single matching element or null if not found
216
 */
217
function queryByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;
218

219
/**
220
 * Query element by placeholder text
221
 * @param container - Container element to search within
222
 * @param text - Placeholder text to search for (string or regex)
223
 * @param options - Text matching options
224
 * @returns Single matching element or null if not found
225
 */
226
function queryByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;
227

228
/**
229
 * Query element by alt attribute
230
 * @param container - Container element to search within
231
 * @param text - Alt text to search for (string or regex)
232
 * @param options - Text matching options
233
 * @returns Single matching element or null if not found
234
 */
235
function queryByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;
236

237
/**
238
 * Query element by title attribute
239
 * @param container - Container element to search within
240
 * @param text - Title text to search for (string or regex)
241
 * @param options - Text matching options
242
 * @returns Single matching element or null if not found
243
 */
244
function queryByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;
245

246
/**
247
 * Query form element by display value
248
 * @param container - Container element to search within
249
 * @param value - Display value to search for (string or regex)
250
 * @param options - Text matching options
251
 * @returns Single matching element or null if not found
252
 */
253
function queryByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;
254

255
/**
256
 * Query element by any attribute
257
 * @param container - Container element to search within
258
 * @param attribute - Attribute name
259
 * @param value - Attribute value to search for (string or regex)
260
 * @param options - Text matching options
261
 * @returns Single matching element or null if not found
262
 */
263
function queryByAttribute(container: HTMLElement, attribute: string, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;
264
```
265

266
### queryAllBy* Queries
267

268
Synchronous queries that return an empty array if no matching elements are found.
269

270
```typescript { .api }
271
/**
272
 * Query all elements by ARIA role
273
 * @param container - Container element to search within
274
 * @param role - ARIA role to search for
275
 * @param options - Additional options for role matching
276
 * @returns Array of matching elements (empty if none found)
277
 */
278
function queryAllByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement[];
279

280
/**
281
 * Query all elements by text content
282
 * @param container - Container element to search within
283
 * @param text - Text content to search for (string or regex)
284
 * @param options - Text matching options
285
 * @returns Array of matching elements (empty if none found)
286
 */
287
function queryAllByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
288

289
/**
290
 * Query all elements by test-id attribute
291
 * @param container - Container element to search within
292
 * @param testId - Test ID attribute value to search for
293
 * @param options - Text matching options
294
 * @returns Array of matching elements (empty if none found)
295
 */
296
function queryAllByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement[];
297

298
/**
299
 * Query all elements by label text
300
 * @param container - Container element to search within
301
 * @param text - Label text to search for (string or regex)
302
 * @param options - Text matching options
303
 * @returns Array of matching elements (empty if none found)
304
 */
305
function queryAllByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
306

307
/**
308
 * Query all elements by placeholder text
309
 * @param container - Container element to search within
310
 * @param text - Placeholder text to search for (string or regex)
311
 * @param options - Text matching options
312
 * @returns Array of matching elements (empty if none found)
313
 */
314
function queryAllByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
315

316
/**
317
 * Query all elements by alt attribute
318
 * @param container - Container element to search within
319
 * @param text - Alt text to search for (string or regex)
320
 * @param options - Text matching options
321
 * @returns Array of matching elements (empty if none found)
322
 */
323
function queryAllByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
324

325
/**
326
 * Query all elements by title attribute
327
 * @param container - Container element to search within
328
 * @param text - Title text to search for (string or regex)
329
 * @param options - Text matching options
330
 * @returns Array of matching elements (empty if none found)
331
 */
332
function queryAllByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
333

334
/**
335
 * Query all form elements by display value
336
 * @param container - Container element to search within
337
 * @param value - Display value to search for (string or regex)
338
 * @param options - Text matching options
339
 * @returns Array of matching elements (empty if none found)
340
 */
341
function queryAllByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
342

343
/**
344
 * Query all elements by any attribute
345
 * @param container - Container element to search within
346
 * @param attribute - Attribute name
347
 * @param value - Attribute value to search for (string or regex)
348
 * @param options - Text matching options
349
 * @returns Array of matching elements (empty if none found)
350
 */
351
function queryAllByAttribute(container: HTMLElement, attribute: string, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];
352
```
353

354
### findBy* Queries
355

356
Asynchronous queries that return a Promise. The Promise resolves when a matching element is found, or rejects if no element is found within the timeout period. All findBy* queries are instrumented for Storybook interactions.
357

358
```typescript { .api }
359
/**
360
 * Async find element by ARIA role
361
 * @param container - Container element to search within
362
 * @param role - ARIA role to search for
363
 * @param options - Additional options for role matching
364
 * @param waitForOptions - Timeout and retry options
365
 * @returns Promise that resolves to single matching element
366
 * @throws Error if no element found within timeout
367
 */
368
function findByRole(container: HTMLElement, role: string, options?: ByRoleOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
369

370
/**
371
 * Async find element by text content
372
 * @param container - Container element to search within
373
 * @param text - Text content to search for (string or regex)
374
 * @param options - Text matching options
375
 * @param waitForOptions - Timeout and retry options
376
 * @returns Promise that resolves to single matching element
377
 * @throws Error if no element found within timeout
378
 */
379
function findByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
380

381
/**
382
 * Async find element by test-id attribute
383
 * @param container - Container element to search within
384
 * @param testId - Test ID attribute value to search for
385
 * @param options - Text matching options
386
 * @param waitForOptions - Timeout and retry options
387
 * @returns Promise that resolves to single matching element
388
 * @throws Error if no element found within timeout
389
 */
390
function findByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
391

392
/**
393
 * Async find element by label text
394
 * @param container - Container element to search within
395
 * @param text - Label text to search for (string or regex)
396
 * @param options - Text matching options
397
 * @param waitForOptions - Timeout and retry options
398
 * @returns Promise that resolves to single matching element
399
 * @throws Error if no element found within timeout
400
 */
401
function findByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
402

403
/**
404
 * Async find element by placeholder text
405
 * @param container - Container element to search within
406
 * @param text - Placeholder text to search for (string or regex)
407
 * @param options - Text matching options
408
 * @param waitForOptions - Timeout and retry options
409
 * @returns Promise that resolves to single matching element
410
 * @throws Error if no element found within timeout
411
 */
412
function findByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
413

414
/**
415
 * Async find element by alt attribute
416
 * @param container - Container element to search within
417
 * @param text - Alt text to search for (string or regex)
418
 * @param options - Text matching options
419
 * @param waitForOptions - Timeout and retry options
420
 * @returns Promise that resolves to single matching element
421
 * @throws Error if no element found within timeout
422
 */
423
function findByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
424

425
/**
426
 * Async find element by title attribute
427
 * @param container - Container element to search within
428
 * @param text - Title text to search for (string or regex)
429
 * @param options - Text matching options
430
 * @param waitForOptions - Timeout and retry options
431
 * @returns Promise that resolves to single matching element
432
 * @throws Error if no element found within timeout
433
 */
434
function findByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
435

436
/**
437
 * Async find form element by display value
438
 * @param container - Container element to search within
439
 * @param value - Display value to search for (string or regex)
440
 * @param options - Text matching options
441
 * @param waitForOptions - Timeout and retry options
442
 * @returns Promise that resolves to single matching element
443
 * @throws Error if no element found within timeout
444
 */
445
function findByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;
446
```
447

448
### findAllBy* Queries
449

450
Asynchronous queries that return a Promise resolving to an array of elements. All findAllBy* queries are instrumented for Storybook interactions.
451

452
```typescript { .api }
453
/**
454
 * Async find all elements by ARIA role
455
 * @param container - Container element to search within
456
 * @param role - ARIA role to search for
457
 * @param options - Additional options for role matching
458
 * @param waitForOptions - Timeout and retry options
459
 * @returns Promise that resolves to array of matching elements
460
 * @throws Error if no elements found within timeout
461
 */
462
function findAllByRole(container: HTMLElement, role: string, options?: ByRoleOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
463

464
/**
465
 * Async find all elements by text content
466
 * @param container - Container element to search within
467
 * @param text - Text content to search for (string or regex)
468
 * @param options - Text matching options
469
 * @param waitForOptions - Timeout and retry options
470
 * @returns Promise that resolves to array of matching elements
471
 * @throws Error if no elements found within timeout
472
 */
473
function findAllByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
474

475
/**
476
 * Async find all elements by test-id attribute
477
 * @param container - Container element to search within
478
 * @param testId - Test ID attribute value to search for
479
 * @param options - Text matching options
480
 * @param waitForOptions - Timeout and retry options
481
 * @returns Promise that resolves to array of matching elements
482
 * @throws Error if no elements found within timeout
483
 */
484
function findAllByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
485

486
/**
487
 * Async find all elements by label text
488
 * @param container - Container element to search within
489
 * @param text - Label text to search for (string or regex)
490
 * @param options - Text matching options
491
 * @param waitForOptions - Timeout and retry options
492
 * @returns Promise that resolves to array of matching elements
493
 * @throws Error if no elements found within timeout
494
 */
495
function findAllByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
496

497
/**
498
 * Async find all elements by placeholder text
499
 * @param container - Container element to search within
500
 * @param text - Placeholder text to search for (string or regex)
501
 * @param options - Text matching options
502
 * @param waitForOptions - Timeout and retry options
503
 * @returns Promise that resolves to array of matching elements
504
 * @throws Error if no elements found within timeout
505
 */
506
function findAllByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
507

508
/**
509
 * Async find all elements by alt attribute
510
 * @param container - Container element to search within
511
 * @param text - Alt text to search for (string or regex)
512
 * @param options - Text matching options
513
 * @param waitForOptions - Timeout and retry options
514
 * @returns Promise that resolves to array of matching elements
515
 * @throws Error if no elements found within timeout
516
 */
517
function findAllByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
518

519
/**
520
 * Async find all elements by title attribute
521
 * @param container - Container element to search within
522
 * @param text - Title text to search for (string or regex)
523
 * @param options - Text matching options
524
 * @param waitForOptions - Timeout and retry options
525
 * @returns Promise that resolves to array of matching elements
526
 * @throws Error if no elements found within timeout
527
 */
528
function findAllByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
529

530
/**
531
 * Async find all form elements by display value
532
 * @param container - Container element to search within
533
 * @param value - Display value to search for (string or regex)  
534
 * @param options - Text matching options
535
 * @param waitForOptions - Timeout and retry options
536
 * @returns Promise that resolves to array of matching elements
537
 * @throws Error if no elements found within timeout
538
 */
539
function findAllByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;
540
```
541

542
## Usage Examples
543

544
```typescript
545
import { within } from "@storybook/testing-library";
546

547
export const QueryExamples = {
548
  play: async ({ canvasElement }) => {
549
    const canvas = within(canvasElement);
550
    
551
    // Synchronous queries - throw if not found
552
    const submitButton = canvas.getByRole('button', { name: /submit/i });
553
    const emailInput = canvas.getByLabelText(/email/i);
554
    const errorMessage = canvas.getByTestId('error-message');
555
    
556
    // Query - returns null if not found  
557
    const optionalElement = canvas.queryByText(/optional text/i);
558
    if (optionalElement) {
559
      // Element exists, do something
560
    }
561
    
562
    // Async queries - wait for element to appear
563
    const loadingSpinner = await canvas.findByTestId('loading');
564
    const results = await canvas.findAllByRole('listitem');
565
  }
566
};
567
```