UNPKG

23.2 kBMarkdownView Raw
1The cf-tables component formats tables, and provides an easy way to make
2tables sortable. The [`cf-core`](../core) component is a dependency of
3this component."
4
5> NOTE: If you use `cf-tables.less` directly,
6 be sure to run the file through
7 [Autoprefixer](https://github.com/postcss/autoprefixer),
8 or your compiled Capital Framework CSS will
9 not work perfectly in older browsers.
10
11
12## Table of contents
13
14- [Variables](#variables)
15 - [Color variables](#color-variables)
16- [Striped tables](#striped-tables)
17- [Right-aligned cells](#right-aligned-cells)
18- [Tables with row links](#tables-with-row-links)
19- [Sortable tables](#sortable-tables)
20 - [Making a table sortable](#making-a-table-sortable)
21 - [Sorting type](#sorting-type)
22 - [Sorting table on page load](#sorting-table-on-page-load)
23 - [Sample sortable table](#sample-sortable-table)
24 - [Important notes about sortable tables](#important-notes-about-sortable-tables)
25- [Responsive tables](#responsive-tables)
26 - [Responsive stacked table](#responsive-stacked-table)
27 - [Responsive stacked table with header](#responsive-stacked-table-with-header)
28 - [Responsive table - horizontal scroll variation](#responsive-table---horizontal-scroll-variation)
29
30
31## Variables
32
33Theme variables for setting the color and sizes throughout the project.
34Overwrite them in your own project by duplicating the variable `@key: value`.
35
36### Color variables
37
38Color variables referenced in comments are from [cf-core cf-brand-colors.less](https://github.com/cfpb/capital-framework/blob/master/src/cf-core/src/cf-brand-colors.less).
39
40```
41@table-head-bg: @gray-5;
42@table-cell-bg: @white;
43@table-cell-bg_alt: @gray-5;
44@table-row-link-bg-hover: @pacific-80;
45@table-row-link-hover-color: @white;
46@table-scrolling-border: @gray-40;
47@table-border: @gray;
48```
49
50
51## Striped tables
52
53The `.o-table__striped` class adds stripes to the `table` rows. This striping is
54not visible on small screens.
55
56<table class="o-table o-table__striped">
57 <thead>
58 <tr>
59 <th>Column 1</th>
60 <th>Column 2</th>
61 <th>Column 3</th>
62 </tr>
63 </thead>
64 <tbody>
65 <tr>
66 <td data-label="Column 1">Row A</td>
67 <td data-label="Column 2">Cell A2</td>
68 <td data-label="Column 3">Cell A3</td>
69 </tr>
70 <tr>
71 <td data-label="Column 1">Row B</td>
72 <td data-label="Column 2">Cell B2</td>
73 <td data-label="Column 3">Cell B3</td>
74 </tr>
75 <tr>
76 <td data-label="Column 1">Row C</td>
77 <td data-label="Column 2">Cell C2</td>
78 <td data-label="Column 3">Cell C3</td>
79 </tr>
80 <tr>
81 <td data-label="Column 1">Row D</td>
82 <td data-label="Column 2">Cell D2</td>
83 <td data-label="Column 3">Cell D3</td>
84 </tr>
85 </tbody>
86</table>
87
88```
89<table class="o-table o-table__striped">
90 <thead>
91 <tr>
92 <th>Column 1</th>
93 <th>Column 2</th>
94 <th>Column 3</th>
95 </tr>
96 </thead>
97 <tbody>
98 <tr>
99 <td data-label="Column 1">Row A</td>
100 <td data-label="Column 2">Cell A2</td>
101 <td data-label="Column 3">Cell A3</td>
102 </tr>
103 <tr>
104 <td data-label="Column 1">Row B</td>
105 <td data-label="Column 2">Cell B2</td>
106 <td data-label="Column 3">Cell B3</td>
107 </tr>
108 <tr>
109 <td data-label="Column 1">Row C</td>
110 <td data-label="Column 2">Cell C2</td>
111 <td data-label="Column 3">Cell C3</td>
112 </tr>
113 <tr>
114 <td data-label="Column 1">Row D</td>
115 <td data-label="Column 2">Cell D2</td>
116 <td data-label="Column 3">Cell D3</td>
117 </tr>
118 </tbody>
119</table>
120```
121
122
123## Right-aligned cells
124
125The use of the `.o-table_cell__right-align` class on a `td` aligns the text
126right - see the third column above.
127
128<table class="o-table o-table__stack-on-small">
129 <thead>
130 <tr>
131 <th>Column 1</th>
132 <th>Column 2</th>
133 <th>Column 3</th>
134 </tr>
135 </thead>
136 <tbody>
137 <tr>
138 <td data-label="Column 1">Row A</td>
139 <td data-label="Column 2">Cell A2</td>
140 <td data-label="Column 3" class="table_cell__right-align">Cell A3</td>
141 </tr>
142 <tr>
143 <td data-label="Column 1">Row B</td>
144 <td data-label="Column 2">Cell B2</td>
145 <td data-label="Column 3" class="table_cell__right-align">Cell B3</td>
146 </tr>
147 </tbody>
148</table>
149
150```
151<table class="o-table o-table__stack-on-small">
152 <thead>
153 <tr>
154 <th>Column 1</th>
155 <th>Column 2</th>
156 <th>Column 3</th>
157 </tr>
158 </thead>
159 <tbody>
160 <tr>
161 <td data-label="Column 1">Row A</td>
162 <td data-label="Column 2">Cell A2</td>
163 <td data-label="Column 3" class="table_cell__right-align">Cell A3</td>
164 </tr>
165 <tr>
166 <td data-label="Column 1">Row B</td>
167 <td data-label="Column 2">Cell B2</td>
168 <td data-label="Column 3" class="table_cell__right-align">Cell B3</td>
169 </tr>
170 </tbody>
171</table>
172```
173
174
175## Tables with row links
176
177The `.o-table_cell__row-links` class is added to a `table` to enable
178highlighting and hyperlinking rows which contain links.
179
180<table class="o-table o-table__row-links">
181 <thead>
182 <tr>
183 <th>Column 1</th>
184 <th>Column 2</th>
185 <th>Column 3</th>
186 </tr>
187 </thead>
188 <tbody>
189 <tr>
190 <td data-label="Column 1">
191 <a href="https://example.com/">Example 1</a>
192 </td>
193 <td data-label="Column 2">Cell A2</td>
194 <td data-label="Column 3" >Cell A3</td>
195 </tr>
196 <tr>
197 <td data-label="Column 1">
198 <a href="https://example.com/">Example 2</a>
199 </td>
200 <td data-label="Column 2">Cell B2</td>
201 <td data-label="Column 3">Cell B3</td>
202 </tr>
203 </tbody>
204</table>
205
206```
207<table class="o-table o-table__row-links">
208 <thead>
209 <tr>
210 <th>Column 1</th>
211 <th>Column 2</th>
212 <th>Column 3</th>
213 </tr>
214 </thead>
215 <tbody>
216 <tr>
217 <td data-label="Column 1">Row A</td>
218 <td data-label="Column 2">Cell A2</td>
219 <td data-label="Column 3">Cell A3</td>
220 </tr>
221 <tr>
222 <td data-label="Column 1">Row B</td>
223 <td data-label="Column 2">Cell B2</td>
224 <td data-label="Column 3">Cell B3</td>
225 </tr>
226 </tbody>
227</table>
228```
229
230
231## Sortable tables
232
233The cf-tables module also includes a sortable table utility.
234
235### Making a table sortable
236
237By adding the `.o-table__sortable` class to a `table`, the `table` becomes sortable.
238To allow the `table` to be sorted by a column, add a `button` to the `th` of the
239column like so:
240
241```
242<button class="sortable">
243 Column Name
244</button>
245```
246
247The use of a `button` helps address certain accessibility concerns.
248
249### Sorting type
250
251To sort properly, the type of the `data` can be specified. By default, the
252column's values will be sorted as `string` values. However, the column can be
253specifically sorted by `number` values (in which case, the cell's contents are
254stripped of non-numeric characters, then sorted by the resulting number). To
255see an example, the sample table later in this document sorts the "Distance"
256column by `number` value.
257
258To sort by `number` value, add the `data-sort_type="number"` attribute
259to the sorting button:
260
261```
262<table class="o-table o-table__sortable">
263 ...
264 <th>
265 <button class="sortable" data-sort_type="number">Column Name</button>
266 </th>
267 ...
268</table>
269```
270
271### Sorting table on page load
272
273To sort the table on page load, use the `.sorted-up` and `.sorted-up` classes:
274
275```
276<table class="o-table o-table__sortable">
277 ...
278 <th>
279 <button class="sortable sorted-up">Column Name</button>
280 </th>
281 ...
282</table>
283```
284
285- `.sorted-up` starts with the column sorted smallest to largest (or
286lowest to highest)
287
288- `.sorted-down` starts with the column sorted largest to smallest (or
289highest to lowest)
290
291### Sample sortable table
292
293<table class="o-table o-table__sortable">
294 <thead>
295 <tr>
296 <th>
297 Agency
298 </th>
299 <th>
300 <button class="sortable">
301 Languages
302 </button>
303 </th>
304 <th>
305 <button class="sortable sorted-up" data-sort_type="number">
306 Distance
307 </button>
308 </th>
309 </tr>
310 </thead>
311 <tbody>
312 <tr>
313 <td>
314 Alpha
315 </td>
316 <td data-label="Languages">
317 English
318 </td>
319 <td data-label="Distance">
320 2.6 mi
321 </td>
322 </tr>
323 <tr>
324 <td>
325 Beta
326 </td>
327 <td data-label="Languages">
328 English, Spanish
329 </td>
330 <td data-label="Distance">
331 1.4 mi
332 </td>
333 </tr>
334 <tr>
335 <td>
336 Gamma
337 </td>
338 <td data-label="Languages">
339 English, French, Spanish
340 </td>
341 <td data-label="Distance">
342 1.4 mi
343 </td>
344 </tr>
345 <tr>
346 <td>
347 Delta
348 </td>
349 <td data-label="Languages">
350 English, Spanish
351 </td>
352 <td data-label="Distance">
353 3.2 mi
354 </td>
355 </tr>
356 <tr>
357 <td>
358 Epsilon
359 </td>
360 <td data-label="Languages">
361 English
362 </td>
363 <td data-label="Distance">
364 1.6 mi
365 </td>
366 </tr>
367 <tr>
368 <td>
369 Zeta
370 </td>
371 <td data-label="Languages">
372 English, Spanish
373 </td>
374 <td data-label="Distance">
375 1.2 mi
376 </td>
377 </tr>
378 <tr>
379 <td>
380 Eta
381 </td>
382 <td data-label="Languages">
383 English
384 </td>
385 <td data-label="Distance">
386 11.1 mi
387 </td>
388 </tr>
389 </tbody>
390</table>
391
392```
393<table class="o-table o-table__sortable">
394 <thead>
395 <tr>
396 <th>
397 Agency
398 </th>
399 <th>
400 <button class="sortable">
401 Languages
402 </button>
403 </th>
404 <th>
405 <button class="sortable sorted-up" data-sort_type="number">
406 Distance
407 </button>
408 </th>
409 </tr>
410 </thead>
411 <tbody>
412 <tr>
413 <td>
414 Alpha
415 </td>
416 <td data-label="Languages">
417 English
418 </td>
419 <td data-label="Distance">
420 2.6 mi
421 </td>
422 </tr>
423 <tr>
424 <td>
425 Beta
426 </td>
427 <td data-label="Languages">
428 English, Spanish
429 </td>
430 <td data-label="Distance">
431 1.4 mi
432 </td>
433 </tr>
434 <tr>
435 <td>
436 Gamma
437 </td>
438 <td data-label="Languages">
439 English, French, Spanish
440 </td>
441 <td data-label="Distance">
442 1.4 mi
443 </td>
444 </tr>
445 <tr>
446 <td>
447 Delta
448 </td>
449 <td data-label="Languages">
450 English, Spanish
451 </td>
452 <td data-label="Distance">
453 3.2 mi
454 </td>
455 </tr>
456 <tr>
457 <td>
458 Epsilon
459 </td>
460 <td data-label="Languages">
461 English
462 </td>
463 <td data-label="Distance">
464 1.6 mi
465 </td>
466 </tr>
467 <tr>
468 <td>
469 Zeta
470 </td>
471 <td data-label="Languages">
472 English, Spanish
473 </td>
474 <td data-label="Distance">
475 1.2 mi
476 </td>
477 </tr>
478 <tr>
479 <td>
480 Eta
481 </td>
482 <td data-label="Languages">
483 English
484 </td>
485 <td data-label="Distance">
486 11.1 mi
487 </td>
488 </tr>
489 </tbody>
490</table>
491```
492
493### Important notes about sortable tables
494
495- The class `.sorted-up` refers to a sort from smallest to greatest
496 (first to last), and `.sorted-down` refers to a sort from greatest to smallest
497 (last to first). These classes are added to the TH when sorting occurs.
498- Please note the importance of defining a THEAD and TBODY to preserve
499 the table's header through sorting operations.
500
501
502## Responsive tables
503
504### Responsive stacked table
505
506The `.o-table__stack-on-small` class adds the "stacked" `table` style for small
507screens.
508
509_Please note that tables are not responsive without adding one of the small
510screen classes._
511
512_Also note that the `data-label` attribute is used to label each entry in a `table`
513for small screen responsive views. Always include the `data-label` attribute for
514each cell._
515
516<table class="o-table o-table__stack-on-small">
517 <thead>
518 <tr>
519 <th>Column 1</th>
520 <th>Column 2</th>
521 <th>Column 3</th>
522 </tr>
523 </thead>
524 <tbody>
525 <tr>
526 <td data-label="Column 1">Row A</td>
527 <td data-label="Column 2">Cell A2</td>
528 <td data-label="Column 3">Cell A3</td>
529 </tr>
530 <tr>
531 <td data-label="Column 1">Row B</td>
532 <td data-label="Column 2">Cell B2</td>
533 <td data-label="Column 3">Cell B3</td>
534 </tr>
535 <tr>
536 <td data-label="Column 1">Row C</td>
537 <td data-label="Column 2">Cell C2</td>
538 <td data-label="Column 3">Cell C3</td>
539 </tr>
540 <tr>
541 <td data-label="Column 1">Row D</td>
542 <td data-label="Column 2">Cell D2</td>
543 <td data-label="Column 3">Cell D3</td>
544 </tr>
545 </tbody>
546</table>
547
548```
549<table class="o-table o-table__stack-on-small">
550 <thead>
551 <tr>
552 <th>Column 1</th>
553 <th>Column 2</th>
554 <th>Column 3</th>
555 </tr>
556 </thead>
557 <tbody>
558 <tr>
559 <td data-label="Column 1">Row A</td>
560 <td data-label="Column 2">Cell A2</td>
561 <td data-label="Column 3">Cell A3</td>
562 </tr>
563 <tr>
564 <td data-label="Column 1">Row B</td>
565 <td data-label="Column 2">Cell B2</td>
566 <td data-label="Column 3">Cell B3</td>
567 </tr>
568 <tr>
569 <td data-label="Column 1">Row C</td>
570 <td data-label="Column 2">Cell C2</td>
571 <td data-label="Column 3">Cell C3</td>
572 </tr>
573 <tr>
574 <td data-label="Column 1">Row D</td>
575 <td data-label="Column 2">Cell D2</td>
576 <td data-label="Column 3">Cell D3</td>
577 </tr>
578 </tbody>
579</table>
580```
581
582### Responsive stacked table with header
583
584The `.o-table__entry-header-on-small` class in addition to
585`.o-table__stack-on-small` class changes the first column to be styled as an
586entry header. This style requires both classes be added.
587
588_Note that tables are not responsive without adding one of the small screen
589classes._
590
591_Also note that the `data-label` attribute is used to label each entry.
592Always include the `data-label` attribute for each cell._
593
594<table class="o-table
595 o-table__stack-on-small
596 o-table__entry-header-on-small">
597 <thead>
598 <tr>
599 <th>Column 1</th>
600 <th>Column 2</th>
601 <th>Column 3</th>
602 </tr>
603 </thead>
604 <tbody>
605 <tr>
606 <td data-label="Column 1">Row A</td>
607 <td data-label="Column 2">Cell A2</td>
608 <td data-label="Column 3">Cell A3</td>
609 </tr>
610 <tr>
611 <td data-label="Column 1">Row B</td>
612 <td data-label="Column 2">Cell B2</td>
613 <td data-label="Column 3">Cell B3</td>
614 </tr>
615 <tr>
616 <td data-label="Column 1">Row C</td>
617 <td data-label="Column 2">Cell C2</td>
618 <td data-label="Column 3">Cell C3</td>
619 </tr>
620 <tr>
621 <td data-label="Column 1">Row D</td>
622 <td data-label="Column 2">Cell D2</td>
623 <td data-label="Column 3">Cell D3</td>
624 </tr>
625 </tbody>
626</table>
627
628```
629<table class="o-table
630 o-table__stack-on-small
631 o-table__entry-header-on-small">
632 <thead>
633 <tr>
634 <th>Column 1</th>
635 <th>Column 2</th>
636 <th>Column 3</th>
637 </tr>
638 </thead>
639 <tbody>
640 <tr>
641 <td data-label="Column 1">Row A</td>
642 <td data-label="Column 2">Cell A2</td>
643 <td data-label="Column 3">Cell A3</td>
644 </tr>
645 <tr>
646 <td data-label="Column 1">Row B</td>
647 <td data-label="Column 2">Cell B2</td>
648 <td data-label="Column 3">Cell B3</td>
649 </tr>
650 <tr>
651 <td data-label="Column 1">Row C</td>
652 <td data-label="Column 2">Cell C2</td>
653 <td data-label="Column 3">Cell C3</td>
654 </tr>
655 <tr>
656 <td data-label="Column 1">Row D</td>
657 <td data-label="Column 2">Cell D2</td>
658 <td data-label="Column 3">Cell D3</td>
659 </tr>
660 </tbody>
661</table>
662```
663
664### Responsive table - horizontal scroll variation
665
666The `.o-table-wrapper__scrolling` class must be added to the parent element of
667the `table` (by adding a wrapping `div`, in most cases). The `table` element
668does not need additional markup in this case. The "Comparative with horizontal
669scroll" style also adds striped rows to the table contained within, and remains
670striped on small screens (unlike the `o-table__striped` class, below).
671
672<div class="o-table o-table-wrapper__scrolling">
673 <table>
674 <thead>
675 <tr>
676 <th>Column 1</th>
677 <th>Column 2</th>
678 <th>Column 3</th>
679 <th>Column 4</th>
680 <th>Column 5</th>
681 <th>Column 6</th>
682 <th>Column 7</th>
683 <th>Column 8</th>
684 </tr>
685 </thead>
686 <tbody>
687 <tr>
688 <td data-label="Column 1">Row A</td>
689 <td data-label="Column 2">Cell A2</td>
690 <td data-label="Column 3">Cell A3</td>
691 <td data-label="Column 4">Cell A4</td>
692 <td data-label="Column 5">Cell A5</td>
693 <td data-label="Column 6">Cell A6</td>
694 <td data-label="Column 7">Cell A7</td>
695 <td data-label="Column 8">Cell A8</td>
696 </tr>
697 <tr>
698 <td data-label="Column 1">Row B</td>
699 <td data-label="Column 2">Cell B2</td>
700 <td data-label="Column 3">Cell B3</td>
701 <td data-label="Column 4">Cell B4</td>
702 <td data-label="Column 5">Cell B5</td>
703 <td data-label="Column 6">Cell B6</td>
704 <td data-label="Column 7">Cell B7</td>
705 <td data-label="Column 8">Cell B8</td>
706 </tr>
707 <tr>
708 <td data-label="Column 1">Row C</td>
709 <td data-label="Column 2">Cell C2</td>
710 <td data-label="Column 3">Cell C3</td>
711 <td data-label="Column 4">Cell C4</td>
712 <td data-label="Column 5">Cell C5</td>
713 <td data-label="Column 6">Cell C6</td>
714 <td data-label="Column 7">Cell C7</td>
715 <td data-label="Column 8">Cell C8</td>
716 </tr>
717 <tr>
718 <td data-label="Column 1">Row D</td>
719 <td data-label="Column 2">Cell D2</td>
720 <td data-label="Column 3">Cell D3</td>
721 <td data-label="Column 4">Cell D4</td>
722 <td data-label="Column 5">Cell D5</td>
723 <td data-label="Column 6">Cell D6</td>
724 <td data-label="Column 7">Cell D7</td>
725 <td data-label="Column 8">Cell D8</td>
726 </tr>
727 </tbody>
728 </table>
729</div>
730
731```
732<div class="o-table o-table-wrapper__scrolling">
733 <table>
734 <thead>
735 <tr>
736 <th>Column 1</th>
737 <th>Column 2</th>
738 <th>Column 3</th>
739 <th>Column 4</th>
740 <th>Column 5</th>
741 <th>Column 6</th>
742 <th>Column 7</th>
743 <th>Column 8</th>
744 </tr>
745 </thead>
746 <tbody>
747 <tr>
748 <td data-label="Column 1">Row A</td>
749 <td data-label="Column 2">Cell A2</td>
750 <td data-label="Column 3">Cell A3</td>
751 <td data-label="Column 4">Cell A4</td>
752 <td data-label="Column 5">Cell A5</td>
753 <td data-label="Column 6">Cell A6</td>
754 <td data-label="Column 7">Cell A7</td>
755 <td data-label="Column 8">Cell A8</td>
756 </tr>
757 <tr>
758 <td data-label="Column 1">Row B</td>
759 <td data-label="Column 2">Cell B2</td>
760 <td data-label="Column 3">Cell B3</td>
761 <td data-label="Column 4">Cell B4</td>
762 <td data-label="Column 5">Cell B5</td>
763 <td data-label="Column 6">Cell B6</td>
764 <td data-label="Column 7">Cell B7</td>
765 <td data-label="Column 8">Cell B8</td>
766 </tr>
767 <tr>
768 <td data-label="Column 1">Row C</td>
769 <td data-label="Column 2">Cell C2</td>
770 <td data-label="Column 3">Cell C3</td>
771 <td data-label="Column 4">Cell C4</td>
772 <td data-label="Column 5">Cell C5</td>
773 <td data-label="Column 6">Cell C6</td>
774 <td data-label="Column 7">Cell C7</td>
775 <td data-label="Column 8">Cell C8</td>
776 </tr>
777 <tr>
778 <td data-label="Column 1">Row D</td>
779 <td data-label="Column 2">Cell D2</td>
780 <td data-label="Column 3">Cell D3</td>
781 <td data-label="Column 4">Cell D4</td>
782 <td data-label="Column 5">Cell D5</td>
783 <td data-label="Column 6">Cell D6</td>
784 <td data-label="Column 7">Cell D7</td>
785 <td data-label="Column 8">Cell D8</td>
786 </tr>
787 </tbody>
788 </table>
789</div>
790```