@ithaka/bonsai/documentation/pages/components/tables.md

ITHAKA core styling

---
title: Tables
description: Succinctly display complex, inter-related, and/or high volumes of data in one view.
foundation: http://foundation.zurb.com/sites/docs/table.html
sass: ./scss/_tables.scss
---

## How to Use
Besides the `<caption>` describing the table as a whole, `<table>`s are comprised of two main sections:
1. The `<thead>` containing heading information (`<th>`) describing the keys and labeling the attributes shared by each item, 
1. The `<tbody>` containing the rows of data (one for each element) with data cells for each column (`<td>`). 

### Simple 

The most basic tables relate multiple similar items to one another by aligning their shared attributes in a one-to-one mapping.

```html_example
<table>
    <caption class="visuallyhidden">Table Title</caption>
    <thead>
        <tr>
            <th scope="col">Attribute 1 - Key</th>
            <th scope="col">Attribute 2 - Key</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>item 1 - attribute 1 value</td>
            <td>item 1 - attribute 2 value</td>
        </tr>
        <tr>
            <td>item 2 - attribute 1 value</td>
            <td>item 2 - attribute 2 value</td>
        </tr>
    </tbody>
</table>
```

#### Accessibility 
For basic tables, ensure that table headers (`<th>`) are used with an appropriate `scope="col"` attribute and a helpful name.

### Complex 

More complex tables can communicate more intricate relationships among items.

```html_example
<table>
    <caption class="visuallyhidden">Complex Table Example</caption>
    <thead>
        <tr>
            <td scope="col" class="visuallyhidden">grouping</td>
            <th scope="col">item name</th>
            <th scope="col">attribute 1 - Key</th>
            <th scope="col">attribute 2 - Key</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <th rowspan="2" scope="row">group 1</th>
            <th scope="row">item 1</th>
            <td>item 1 attribute 1 value</td>
            <td>item 1 attribute 2 value</td>
        </tr>
        <tr>
            <th scope="row">item 2</th>
            <td>item 2 attribute 1 value</td>
            <td>item 2 attribute 2 value</td>
        </tr>
        <tr>
            <th scope="row">group 2</th>
            <th scope="row">item 3</th>
            <td>item 3 attribute 1 value</td>
            <td>item 3 attribute 2 value</td>
        </tr>
    </tbody>
</table>
```

### Accessibility 
Applying `scope` to more complex tables makes otherwise illegible information more sensible to screen readers. 

## Examples 

In context, it is often useful to put content other than plain text within a table

```html_example
<table>
    <caption class="visuallyhidden">Browse JSTOR by title.</caption>
    <thead>
        <tr>
            <th scope="col">0-9</th>
            <th scope="col">Published Date</th>
            <th scope="col" class="visuallyhidden right">Download Button</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><a href="#">14th Century English Mystics Newsletter</a></td>
            <td>1974-1983</td>
            <td class="txtr"><a href="#" class="button secondary">Download (xls)</a></td> 
        </tr>
        <tr>
            <td><a href="#">19th-Century Music</a></td>
            <td>1977-2015</td>
            <td class="txtr"><a href="#" class="button secondary">Download (xls)</a></td>
        </tr>
        <tr>
            <td><a href="#">291</a></td>
            <td>1915-1916</td>
            <td class="txtr"><a href="#" class="button secondary">Download (xls)</a></td>
        </tr>
    </tbody>
</table>
```
## Guidelines: 
1. You can use `.visuallyhidden` to hide sections of the table from the visual design while
  maintaining valuable context in the DOM for screen reader users.
2. You can use the [spacing classes](/styleguide/spacing.html) to alter the alignment of columns and column headings. 

## Accessibility 
1. Ensure that all tables have a caption, even if that caption is `.visuallyhidden`.
2. Make sure to meaningfully name all columns and rows, even if that column is `.visuallyhidden`.


## Avoid
1. Using tables for simple one-to-one matchings better communicated with a definitional list (`<dl>`).
2. Using tables to format or organize a page or component into sections (use `.row` and `.columns` for that).