danger
COVID-19 Risk Level for Multnomah County: High Risk

Using Tables for Data on Portland.gov

Data tables on Portland.gov display tabular data in an accessible grid format.

On this page

Introduction to Tables

While creating content on Portland.gov, you might need to place data in a table. Tables are used to organize appropriate data into a grid format. This guide will detail when and how to use them. Constructed carelessly, tables can cause a poor user experience, are harder for you as an editor to maintain,  and affect search engine optimization (SEO) — meaning your content becomes harder to find. Well-designed and accessible tables, on the other hand, are powerful tools for informing the public. 

Should I Use a Table?

Before creating a table you should ask yourself: is this the best way to present the information? If you're using a table simply to define your page layout into a two-column list of committee members, for instance, that would not be the best way (we would suggest a single unordered list for that.) A table should typically be reserved for either a set of variable-value pairs, or data across a matrix of two variables.

A variable-value table might be a public notice that has a notice ID, notice title, notice start date, and a notice end date. The first column of the table would hold the item names (ID, title, dates) in each row, and the second column would have the corresponding value (#2201, "Foreclosure Sale at 123 SW Main," 9/30/2020). 

A matrix table has headers both down the first column and across the first row, and the remaining cells hold the data for each variable pair. In the below table, the variables are coffee types, and coffee additives. Cappucino (a coffee type) has milk (an additive), but macchiato does not. So the cell for the intersection of cappuccino and milk holds the value "Yes," while the intersection of macchiato and milk holds "No." 

There are some limited options available on Portland.gov for adding complexity to the above examples, but the limitations of the web reading experience need to be taken into account when creating tables. Responsive styling automatically resizes content so it fits on your device's display, but tables still can be a cumbersome experience for users on mobile phones.  Mobile device users make up about half of the visits to our website, and for some content, this percentage is higher and trending upward. Even simple tables can feel hard to navigate and comprehend in the smaller format.

Image of a data table from Portland.gov
Example of data-table on a desktop
An image showing a data table being cut off on a mobile device
An example of a data-table on a mobile device

The preceding table images show how a large display may appear versus a smaller display. The table becomes harder to read and navigate on a mobile device: it is too wide for the screen, and the user must scroll horizontally to see the rest. 

Tables are often troublesome for assistive devices such as screen readers. Roughly one in four Americans are diagnosed with a disability and even more live without being treated. Creating accessible content is imperative to creating good content.

Your own eyes may visually group table information in a certain way, but to assistive devices it will be read, “cell 1, cell 2, cell3, etc...” The lack of proper formatting can thus be a challenging experience. Below is a video example of a table without proper headers, being read aloud by a screen reader:

Summary of Best Practices

  • Avoid using tables for layout
  • Define all headers, to add semantic structure to the tables
  • Summarize the content of the table in an accompanying narrative

Now let’s view some examples of accessible tables on Portland.gov.

Column Header Sample HTML

All tables are built row by row, but headers are read first and will provide emphasis to assistive devices. Here is an example of a table with the first row as the heading:

Coffee order for the office
Coffee TypesOrders
Cappuccino2
Macchiato1
Flat White2
Latte3
The html and css displayed in this image will be described in the next section

Allowable table classes for Portland.gov are: 

  • table-responsive: Responsive tables allow tables to be scrolled horizontally with ease. Within <div class=”table-responsive”>.
  • table-hover: enable a hover state on table rows within <tbody>.
  • table-bordered: borders on all sides of the table and cells.
  • thead-dark: a dark color scheme to establish the table heading row.
  • table-sm: an optional class that creates a more compact table with less padding.
  • scope: adds bolded font to your table column headings but will also provide context to assisted devices providing a better user experience for all of our users.

Column and Row Headers Sample HTML

For tables that present values based on two variables at once (does it have a specific coffee additive, depending on a specific type of coffee?),  giving HTML scope to the rest of the rows in the first column will not only create a secondary header in bold type, but will also be read by assistive devices as a subheading. This allows assisted users to follow along more easily. Note in the HTML code that in addition to the scoped columns, each row in the first column now is scoped by row. 

Comparison between different types of coffee drinks
Coffee TypesMilkEspresso ShotsMilk Foam
CappuccinoYes2Yes
MacchiatoNo1Yes
Flat WhiteYes1No
LatteYes1Yes
The html described in this image will be explained in the next section

Data that Span Multiple Columns or Rows

To make your tables easier to understand, we ask you to limit the use of spanning data across columns or rows. If you find you are using spanning often in your tables, it may indicate better readability if the tables are broken into smaller pieces: instead of one table that tries to cover (span) park activity fees for three types of customers, one smaller table for each customer type may be the better solution. 

Multiple Columns

Column span allows headers to be used across multiple columns. The <colspan> tag spans a column across multiple cells.

Boiling points for liquids
Boiling PointTimeTemperature
Water12 minutes100℃220℉

Multiple Rows

To span across multiple rows, utilize a row span. The <rowspan> tag spans a row across multiple cells.

Brewing instructions for different hot and cold brewed coffee
Coffee StrengthCoffee Blend
Dark RoastSignature Roast
Dark Blend
The html and css in this image shows data-table row spans and will be described in the next section

Contact

Portland.gov Website Support