How the Description List Element improves Accessibility and the Developer Experience

Lists are among the basic building blocks of the web. Every web developer knows the HTML elements <ul> and <ol> for unordered and ordered lists. Yet few are familiar with their close relative <dl>, the description list.

A typical use case for the element is to implement a glossary with terms and definitions. In fact, you can do a lot more with it. I would argue that any list of key-value pairs should be marked up as a description list. It improves the developer experience by making the code more readable. And it makes your content more accessible.

Two people discussing the HTML code on the laptop monitor in front of them. Photo: © Ketut Subiyanto / pexels.com

We'll take a look at the history of the element, see how it works and how it affects accessibility.

A Quick History of the Description List Element

The <dl> element has existed since HTML+ in the year 1993. The document defined the element as a “definition list”:

A definition list is a list of terms and corresponding definitions. Definition lists are typically formatted with the term flush-left and the definition, formatted paragraph style, indented after the term.

This narrow definition is still present in many minds today. But it no longer applies. The element's definition was changed in HTML5, making it more versatile:

The dl element represents an association list consisting of zero or more name-value groups (a description list). [...] Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data.

This means that the element can be used to markup any list of key-value pairs. For example, a list of metadata about a client: name, address, telephone number, etc.

How to use the <dl> element

The description list contains a list of terms and descriptions that are defined with the HTML elements <dt> (description term) and <dd> (description details). Here's an example for a list of metadata:

<dl> <dt>Account Owner</dt> <dd>Martina Musterfrau</dd> <dt>Banking Institute</dt> <dd>Musterbank</dd> <dt>IBAN</dt> <dd>AT12 3456 7891 2345 6789</dd> <dt>Telephone</dt> <dd>+43 1234 56 78</dd> </dl>

The semantic HTML tags convey important information to assistive technologies. Screen readers can navigate the individual list items and convey the relationship between term and description. But web developers also benefit from the semantic markup. Imagine the example above as a sequence of <div> elements:

<div class="metadata"> <div class="term">Account Owner</div> <div class="description">Martina Musterfrau</div> <div class="term">Banking Institute</div> <div class="description">Musterbank</div> <div class="term">IBAN</div> <div class="description">AT12 3456 7891 2345 6789</div> <div class="term">Telephone</div> <div class="description">+43 1234 56 78</div> </div>

I hope you agree with me that the semantic HTML is easier to understand and work with. You can also leverage the semantic tag names for expressive and easy to understand CSS selectors. Check out my article “3 Ways how Web Developers also benefit from Accessibility”.

Styling the Description List

The standard styling of description lists is rather bland. But don't worry! You can freely customize the element with CSS. The HTML specification allows wrapping each key-value pair in a <div> element.

<dl> <div> <dt>Account Owner</dt> <dd>Martina Musterfrau</dd> </div> <div> <dt>Banking Institute</dt> <dd>Musterbank</dd> </div> <div> <dt>IBAN</dt> <dd>AT12 3456 7891 2345 6789</dd> </div> </dl>

This content structure enables us to create a responsive, horizontal layout using CSS flexbox:

dl { display: flex; flex-wrap: wrap; gap: 1rem; } dl > div { flex-grow: 1; } dt { color: #6e2755; font-size: 0.9rem; font-weight: bold; } dd { font-size: 1rem; margin-inline-start: 0; }

Here's the end result:

Screen Reader Support

The description list element makes your content more accessible, especially for screen reader users. There are minor differences between browsers and screen readers, but overall the support is generally good. Adrian Roselli has done extensive screen reader testing for his article “Brief Note on Description List Support”. Go check it out!

I'd like to add one important aspect to his analysis: Screen readers are software applications. And software can have bugs or miss an important feature (like the correct handling of the <dl> element). But this should not stop us from using this feature. Especially if we can expect the screen reader vendor to fix their mistakes in the near future.

Posted on