Semantic HTML - Headings, Tables, Lists, and more.

August 28, 2022

It is important to include things in semantic HTML at all times. Well most times (sometimes ARIA can be used but its not recommended unless you know what your doing).

So what do I mean by including things into semantic HTML?

When I say semantic html its important to ensure our content is appropriately marked up and that our contents layout/structure/relationships are not referenced by visuals only.

Headings

You need to ensure all things that should be headings are actual headings (h1, h2, h3, h4, h5, h6) and not just styled to look like headings. Also its best to ensure that you write headings in hierarchial order. This means h1, then after that would be an h2, not an h6.

Heading examples

Good example of semantic headings

    <h2 id="heading-good-example">Good example of semantic headings</h2>

This heading is a good example of a semantic heading because it allows screen-reader users to be able to easily look for a heading/section of content since it appropriately marked up.

Heading that is not semantic

<p id="heading-bad-example">Heading that is not semantic</p>

Looks like a heading isn't a heading. This heading isn't semantically set up as a real heading so it causes screen-readers to not notice it as an actual heading.

Lists

Any items that should be a list or if they are a group of links should be in one of the following list markups:

ol - Ordered list for when order does matter
ul - Unordered list for when the order does'nt matter
dl - when a term should be paired with a definition
- dt - term name
- dd - term definition When a screen reader user comes across a list it will notify them that its a list and how many list items it contains. That way a user will understand what they are listening to and what they can expect.

List examples

Good semantic lists

Ordered list

List item 1
List item 2
List item 3

<ol>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
</ol>

Unordered list

List item 1
List item 2
List item 3

<ul>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
</ul>

Definition list

Term 1: Some cool term definition

      <dl>
      <dt>Term 1</dt>
        <dd>
          Some cool term definition
        </dd>
    </dl>

Bad semantic list

1. Bad list item
2. Bad list item
3. Bad list item

<p>1. Bad list item<br>
2. Bad list item<br>
3. Bad list item</p>

Tables

Tables are a beast in their own thing. They never truly will be 100% accessible even if we do everything right, but this still does'nt mean we should do things wrong. The goal is to make them as accessible as possible by ensuring they have the following:

Table headers <th>
Rows <tr> & Columns
Data-sets that appropriately link the data to the correct headers
Title - should have an aria-labelled to linking to a visible heading above the table. If there is no visible heading above the table then should have an aria-label or a caption.

Basic table example

Name	1 mile	5 km	10 km
Mary	8:32	28:04	1:01:16
Betsy	7:43	26:47	55:38

    
    <table class="table" tabindex="0" aria-labelledby="basic-table">
  <thead>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">1 mile</th>
      <th scope="col">5 km</th>
      <th scope="col">10 km</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Mary</td>
      <td>8:32</td>
      <td>28:04</td>
      <td>1:01:16</td>
    </tr>
    <tr>
      <td>Betsy</td>
      <td>7:43</td>
      <td>26:47</td>
      <td>55:38</td>
    </tr>
  </tbody>
</table>

Table with group headers example

	Heading 1		Heading 2
	Heading 3	Data		Data
Heading 4	Data		Data


<table  class="table table-colgroup" tabindex="0" aria-labelledby="group-headers">
  <thead>
    <tr>
      <td rowspan="2"> </td>
      <th colspan="2" scope="colgroup" class="theader">Heading 1</th>
      <th colspan="2" scope="colgroup" class="theader">Heading 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Heading 3</th>
      <td colspan="2">Data</td>
      <td colspan="2">Data</td>
    </tr>
    <tr>
      <th scope="row">Heading 4</th>
      <td colspan="2">Data</td>
      <td colspan="2">Data</td>
    </tr>
  </tbody>
</table>

Complex table example

If a table has complex data you will need to use headers and ID's this will help associate the correct data with the correct header.

Header 1	Header 2
	Subheader 1	Subheader 2
	Row header 1	Data 1	Data 2
Row header 2	Data 3	Data 4

    
<table class="table-complex" tabindex="0" aria-labelledby="complex">
  <thead>
    <tr>
      <th role="columnheader" rowspan="3" id="h1">Header 1</th>
      <th colspan="3" role="columnheader" id="h2">Header 2</th>
    </tr>
    <tr>
      <th role="columnheader" id="s1">Subheader 1</th>
      <th role="columnheader" id="s2">Subheader 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="rowheader" id="row1" headers="h1">Row header 1</th>
      <td headers="row1 h2 s1">Data 1</td>
      <td headers="h2 s2 row1">Data 2</td>
    </tr>
    <tr>
      <th scope="rowheader" id="row2" headers="h1">Row header 2</th>
      <td headers="h2 s1 row2">Data 3</td>
      <td headers="h2 s2 row2">Data 4</td>
    </tr>
  </tbody>
</table>

Paragraph examples

This paragraph is inside of the correct HTML

This paragraph is not.