-
Notifications
You must be signed in to change notification settings - Fork 22.5k
/
index.md
432 lines (344 loc) · 14.4 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
---
title: "<tr>: The Table Row element"
slug: Web/HTML/Element/tr
page-type: html-element
browser-compat: html.elements.tr
---
{{HTMLSidebar}}
The **`<tr>`** [HTML](/en-US/docs/Web/HTML) element defines a row of cells in a table. The row's cells can then be established using a mix of {{HTMLElement("td")}} (data cell) and {{HTMLElement("th")}} (header cell) elements.
{{EmbedInteractiveExample("pages/tabbed/tr.html","tabbed-taller")}}
## Attributes
This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes).
### Deprecated attributes
The following attributes are deprecated and should not be used. They are documented below for reference when updating existing code and for historical interest only.
- `align` {{deprecated_inline}}
- : Specifies the horizontal alignment of each row cell. The possible {{Glossary("enumerated")}} values are `left`, `center`, `right`, `justify`, and `char`. When supported, the `char` value aligns the textual content on the character defined in the [`char`](#char) attribute and on offset defined by the [`charoff`](#charoff) attribute. Use the {{cssxref("text-align")}} CSS property instead, as this attribute is deprecated.
- `bgcolor` {{deprecated_inline}}
- : Defines the background color of each row cell. The value is an HTML color; either a [6-digit hexadecimal RGB code](/en-US/docs/Web/CSS/hex-color), prefixed by a '`#`', or a [color keyword](/en-US/docs/Web/CSS/named-color). Other CSS {{cssxref("color_value", "<color>")}} values are not supported. Use the {{cssxref("background-color")}} CSS property instead, as this attribute is deprecated.
- `char` {{deprecated_inline}}
- : Specifies the alignment of the content to a character of each row cell. Typical values for this include a period (`.`) when attempting to align numbers or monetary values. If [`align`](#align) is not set to `char`, this attribute is ignored.
- `charoff` {{deprecated_inline}}
- : Specifies the number of characters to offset the row cell content from the alignment character specified by the [`char`](#char) attribute.
- `valign` {{deprecated_inline}}
- : Specifies the vertical alignment of each row cell. The possible {{Glossary("enumerated")}} values are `baseline`, `bottom`, `middle`, and `top`. Use the {{cssxref("vertical-align")}} CSS property instead, as this attribute is deprecated.
## Usage notes
- The `<tr>` element is valid as a child of a {{HTMLElement("thead")}}, {{HTMLElement("tbody")}}, or {{HTMLElement("tfoot")}} element only.
- If the `<tr>` is placed as a direct child of its parent {{HTMLElement("table")}} element, the `<tbody>` parent is implied and browsers will add the `<tbody>` to the markup.
- The implied `<tbody>` parent is only supported if the `<table>` otherwise has no child `<tbody>` elements, and only if the `<tr>` is included after any {{HTMLElement("caption")}}, {{HTMLElement("colgroup")}}, and `<thead>` elements.
- The CSS pseudo-classes {{cssxref(":nth-of-type")}}, {{cssxref(":first-of-type")}}, and {{cssxref(":last-of-type")}} are often useful for selecting the desired set of rows and their data and header cells ({{HTMLElement("td")}} and {{HTMLElement("th")}} elements).
- When a `<tr>` is included as a direct child of the `<table>`, as the browser adds a `<tbody>` to the markup, CSS selectors such as `table > tr` may not work as expected or at all.
## Examples
See {{HTMLElement("table")}} for a complete table example introducing common standards and best practices.
### Basic row setup
This example demonstrates a table with four rows and three columns, where the first column contains headers for the row data cells.
#### HTML
Four `<tr>` elements are used to create four table rows. Each row contains three cells - one header cell ({{HTMLElement("th")}}) and two data cells ({{HTMLElement("td")}}) - creating three columns. The [`scope`](/en-US/docs/Web/HTML/Element/th#scope) attribute set on each header cell specifies which cells they relate to, which in this example is all data cells within the `row`.
```html
<table>
<tr>
<th scope="row">A</th>
<td>Alfa</td>
<td>AL fah</td>
</tr>
<tr>
<th scope="row">B</th>
<td>Bravo</td>
<td>BRAH voh</td>
</tr>
<tr>
<th scope="row">C</th>
<td>Charlie</td>
<td>CHAR lee</td>
</tr>
<tr>
<th scope="row">D</th>
<td>Delta</td>
<td>DELL tah</td>
</tr>
</table>
```
#### CSS
The CSS {{cssxref(":nth-of-type")}} pseudo-class is used to select every `odd` row and set the {{cssxref("background-color")}} of those rows to a slightly darker tone, creating a so-called "zebra stripe" effect. This alternating background makes the rows of data in the table easier to parse and read—imagine having many rows and columns and trying to find some data in a particular row. In addition, the row header cells ({{HTMLElement("th")}} elements) are highlighted with a {{cssxref("background-color")}} to distinguish them from the data cells ({{HTMLElement("td")}} elements).
```css
tr:nth-of-type(odd) {
background-color: #eee;
}
tr th[scope="row"] {
background-color: #d6ecd4;
}
```
```css hidden
table {
border-collapse: collapse;
border: 2px solid rgb(140 140 140);
font-family: sans-serif;
font-size: 0.8rem;
letter-spacing: 1px;
}
th,
td {
border: 1px solid rgb(160 160 160);
padding: 8px 10px;
}
```
#### Result
{{EmbedLiveSample("Basic_row_setup", 650, 140)}}
### Header row
This example extends the basic table from the [previous example](#basic_row_setup) by adding a header row as the first row of the table.
#### HTML
An additional table row (`<tr>`) is added as the first row of the table with column header cells ({{HTMLElement("th")}}) providing a header for each column. We put this row in a {{HTMLElement("thead")}} grouping element to indicate this is the header of the table. The [`scope`](/en-US/docs/Web/HTML/Element/th#scope) attribute is added to each header cell (`<th>`) within this head row to explicitly specify that each header cell relates to all the cells within its own column, even though those cells are in the {{HTMLElement("tbody")}}.
```html
<table>
<tr>
<th scope="col">Symbol</th>
<th scope="col">Code word</th>
<th scope="col">Pronunciation</th>
</tr>
<tr>
<th scope="row">A</th>
<td>Alfa</td>
<td>AL fah</td>
</tr>
<tr>
<th scope="row">B</th>
<td>Bravo</td>
<td>BRAH voh</td>
</tr>
<tr>
<th scope="row">C</th>
<td>Charlie</td>
<td>CHAR lee</td>
</tr>
<tr>
<th scope="row">D</th>
<td>Delta</td>
<td>DELL tah</td>
</tr>
</table>
```
#### CSS
The CSS is nearly unchanged from the [previous example](#basic_row_setup), except for some additional styling to highlight the "header row" so that the headers of the columns stand out from the other cells.
```css
tr:nth-of-type(odd) {
background-color: #eee;
}
tr th[scope="col"] {
background-color: #505050;
color: #fff;
}
tr th[scope="row"] {
background-color: #d6ecd4;
}
```
```css hidden
table {
border-collapse: collapse;
border: 2px solid rgb(140 140 140);
font-family: sans-serif;
font-size: 0.8rem;
letter-spacing: 1px;
}
th,
td {
border: 1px solid rgb(160 160 160);
padding: 8px 10px;
}
```
#### Result
{{EmbedLiveSample("Header_row", 650, 170)}}
### Sorting rows
There are no native methods for sorting the rows (`<tr>` elements) of a {{HTMLElement("table")}}. But using {{jsxref("Array.prototype.sort()")}}, {{domxref("Node.removeChild")}}, and {{domxref("Node.appendChild")}}, a custom `sort()` function can be implemented in JavaScript to sort an {{domxref("HTMLCollection")}} of `<tr>` elements.
#### HTML
A {{HTMLElement("tbody")}} element is used in this basic table to mark the body section of the table and to include three rows (`<tr>` elements) with data ({{HTMLElement("td")}} elements), creating one column with numbers in descending order.
```html
<table>
<tbody>
<tr>
<td>3</td>
</tr>
<tr>
<td>2</td>
</tr>
<tr>
<td>1</td>
</tr>
</tbody>
</table>
```
#### JavaScript
In the JavaScript code below, the created `sort()` function is attached to the {{HTMLElement("tbody")}} element so that it sorts the table cells in order of increasing value and updates the display accordingly.
```js
HTMLTableSectionElement.prototype.sort = function (cb) {
Array.from(this.rows)
.sort(cb)
.forEach((e) => this.appendChild(this.removeChild(e)));
};
document
.querySelector("table")
.tBodies[0].sort((a, b) => a.textContent.localeCompare(b.textContent));
```
```css hidden
table {
border-collapse: collapse;
border: 2px solid rgb(140 140 140);
font-family: sans-serif;
font-size: 0.8rem;
letter-spacing: 1px;
}
td {
border: 1px solid rgb(160 160 160);
padding: 4px 8px;
}
```
#### Result
{{EmbedLiveSample('Sorting_rows', '650', '80')}}
### Sorting rows with a click on header cells
This example extends the basic table from the [previous example](#sorting_rows) by making the sorting interactive and independent for multiple columns.
#### HTML
An additional data cell ({{HTMLElement("td")}} element) is added to each row (`<tr>` element) within the table body ({{HTMLElement("tbody")}} element) to create a second column with letters in ascending order. Using the {{HTMLElement("thead")}} element, a head section is added before the body section to introduce a head row with table header cells ({{HTMLElement("th")}} element). These header cells are used in the JavaScript code below to make them clickable and then to perform the corresponding sorting when activated per click.
```html
<table>
<thead>
<tr>
<th>Numbers</th>
<th>Letters</th>
</tr>
</thead>
<tbody>
<tr>
<td>3</td>
<td>A</td>
</tr>
<tr>
<td>2</td>
<td>B</td>
</tr>
<tr>
<td>1</td>
<td>C</td>
</tr>
</tbody>
</table>
```
#### JavaScript
A click event handler is added to each table header ({{HTMLElement("th")}} element) of each {{HTMLElement("table")}} in the {{domxref("HTMLDocument", "document")}}; it sorts all the rows (`<tr>` elements) of the {{HTMLElement("tbody")}} based on the contents of the data cells ({{HTMLElement("td")}} elements) contained in the rows.
> [!NOTE]
> This solution assumes that the {{HTMLElement("td")}} elements are populated by raw text with no descendant elements.
```js
const allTables = document.querySelectorAll("table");
for (const table of allTables) {
const tBody = table.tBodies[0];
const rows = Array.from(tBody.rows);
const headerCells = table.tHead.rows[0].cells;
for (const th of headerCells) {
const cellIndex = th.cellIndex;
th.addEventListener("click", () => {
rows.sort((tr1, tr2) => {
const tr1Text = tr1.cells[cellIndex].textContent;
const tr2Text = tr2.cells[cellIndex].textContent;
return tr1Text.localeCompare(tr2Text);
});
tBody.append(...rows);
});
}
}
```
```css hidden
table {
border-collapse: collapse;
border: 2px solid rgb(140 140 140);
font-family: sans-serif;
font-size: 0.8rem;
letter-spacing: 1px;
}
th,
td {
border: 1px solid rgb(160 160 160);
padding: 4px 8px;
}
th {
background-color: #505050;
color: #fff;
cursor: pointer;
}
```
#### Result
{{EmbedLiveSample('Sorting_rows_with_a_click_on_header_cells', '650', '100')}}
> [!NOTE]
> To be usable and accessible, the header cell of each sortable column must be identifiable as a sorting button and each must define whether the column is currently sorted in ascending or descending order visually and with the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) attribute. See the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/)'s [sortable table example](https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/sortable-table/) for more information.
## Technical summary
<table class="properties">
<tbody>
<tr>
<th scope="row">
<a href="/en-US/docs/Web/HTML/Content_categories"
>Content categories</a
>
</th>
<td>None</td>
</tr>
<tr>
<th scope="row">Permitted content</th>
<td>
Zero or more {{HTMLElement("td")}} and/or
{{HTMLElement("th")}} elements;
{{Glossary("script-supporting element", "script-supporting elements")}}
({{HTMLElement("script")}} and
{{HTMLElement("template")}}) are also allowed.
</td>
</tr>
<tr>
<th scope="row">Tag omission</th>
<td>
Start tag is mandatory. End tag may be omitted if the
<code><tr></code> element is immediately followed by a
<code><tr></code> element, or if the row is the last element
in its parent table group ({{HTMLElement("thead")}},
{{HTMLElement("tbody")}} or {{HTMLElement("tfoot")}})
element.
</td>
</tr>
<tr>
<th scope="row">Permitted parents</th>
<td>
{{HTMLElement("table")}} (only if the table has no child
{{HTMLElement("tbody")}} element, and even then only after any
{{HTMLElement("caption")}},
{{HTMLElement("colgroup")}}, and
{{HTMLElement("thead")}} elements); otherwise, the parent must
be a {{HTMLElement("thead")}}, {{HTMLElement("tbody")}} or
{{HTMLElement("tfoot")}} element.
</td>
</tr>
<tr>
<th scope="row">Implicit ARIA role</th>
<td>
<code
><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/row_role"
>row</a
></code
>
</td>
</tr>
<tr>
<th scope="row">Permitted ARIA roles</th>
<td>Any</td>
</tr>
<tr>
<th scope="row">DOM interface</th>
<td>{{DOMxRef("HTMLTableRowElement")}}</td>
</tr>
</tbody>
</table>
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- [Learn: HTML tables](/en-US/docs/Learn/HTML/Tables)
- {{HTMLElement("caption")}}, {{HTMLElement("col")}}, {{HTMLElement("colgroup")}}, {{HTMLElement("table")}}, {{HTMLElement("tbody")}}, {{HTMLElement("td")}}, {{HTMLElement("tfoot")}}, {{HTMLElement("th")}}, {{HTMLElement("thead")}}: Other table-related elements
- {{cssxref("background-color")}}: CSS property to set the background color of each row cell
- {{cssxref("border")}}: CSS property to control borders of row cells
- {{cssxref("text-align")}}: CSS property to horizontally align each row cell content
- {{cssxref("vertical-align")}}: CSS property to vertically align each row cell content
- {{cssxref(":nth-of-type")}}, {{cssxref(":first-of-type")}}, {{cssxref(":last-of-type")}}: CSS pseudo-classes to select the desired row cells