Accessibility pattern · Data display

Description list

A description list pairs each term with its values, so "Shipping address" and the address beside it are tied together, not just placed side by side. Each pair sits in a div, which HTML allows, so it can be laid out as a row; each Edit link carries hidden words that say what it edits.

WCAG criteria
6
Keyboard rules
2
Checked with
axe, keyboard and the inspector
Try it Copy the code All patterns

Live demo

Try it

Use it with a mouse, a keyboard or a screen reader. The inspector beside it shows what the browser tells assistive technology as you go: focus, state changes and announcements.

Order #10428

Placed on 30 Sep 2026

Items
Handwoven cotton throw Qty 1
Brass diya set Qty 2
Shipping address
Asha Rao, 14 Lake View Road, Indiranagar, Bengaluru 560038
Edit shipping address
Delivery
Standard, arriving 9 to 11 October
Edit delivery
Payment
UPI, asha.rao@okbank
Edit payment
Subtotal
₹3,840
Delivery
Free
Total
₹3,840

Profile

Your account details

Name
Asha Rao
Edit name
Email
[email protected]
Edit email
Phone
+91 98765 43210
Edit phone number
Languages
English
Hindi
Kannada
Edit languages
Member since
March 2021

Which element to use

Description list <dl>
Names and values about one thing, like this order or this profile.
Table <table>
The same fields for many things, read across and down, like all your orders.
List <ul>
Items of one kind with no labels, like the products in a basket.

The demo works without JavaScript only as far as its HTML does; the inspector needs JavaScript.

Keyboard

Keys it answers to

Every action works without a pointer.

KeyWhat it does
Tab or ShiftTabMoves through the Edit links in reading order; the terms and values themselves are text, not tab stops.
EnterOn an Edit link, follows it to the form for that row.

Screen readers

What it announces

Written from the roles, names and states in the markup.

WhenExpected announcement
A screen reader reads the order detailsItems, term. Handwoven cotton throw Qty 1, definition. Brass diya set Qty 2, definition
Tab reaches the first Edit linkEdit shipping address, link
Tab reaches the Edit link beside PhoneEdit phone number, link
Enter on an Edit link in this demoIn a real page, this link opens the form for that row.

These are expected announcements, not recordings. Wording and order differ between screen readers and browsers.

Code

Copy the code

The exact files this demo runs on. The styles are served with a prefix that keeps this site's own styles out of the demo; what you copy is the original.

The markup

<div class="ap-dlist" data-ap-dlist>
  <section class="ap-dlist__card" aria-labelledby="dlist-order">
    <div class="ap-dlist__top">
      <h3 class="ap-dlist__name" id="dlist-order">Order #10428</h3>
      <p class="ap-dlist__sub">Placed on 30 Sep 2026</p>
    </div>
    <dl class="ap-dlist__list">
      <div class="ap-dlist__row">
        <dt>Items</dt>
        <dd>Handwoven cotton throw <span class="ap-dlist__qty">Qty 1</span></dd>
        <dd>Brass diya set <span class="ap-dlist__qty">Qty 2</span></dd>
      </div>
      <div class="ap-dlist__row">
        <dt>Shipping address</dt>
        <dd>Asha Rao, 14 Lake View Road, Indiranagar, Bengaluru 560038</dd>
        <dd class="ap-dlist__act"><a class="ap-dlist__edit" href="#edit-address">Edit<span class="ap-dlist__sr"> shipping address</span></a></dd>
      </div>
      <div class="ap-dlist__row">
        <dt>Delivery</dt>
        <dd>Standard, arriving 9 to 11 October</dd>
        <dd class="ap-dlist__act"><a class="ap-dlist__edit" href="#edit-delivery">Edit<span class="ap-dlist__sr"> delivery</span></a></dd>
      </div>
      <div class="ap-dlist__row">
        <dt>Payment</dt>
        <dd>UPI, asha.rao@okbank</dd>
        <dd class="ap-dlist__act"><a class="ap-dlist__edit" href="#edit-payment">Edit<span class="ap-dlist__sr"> payment</span></a></dd>
      </div>
    </dl>
    <dl class="ap-dlist__sums">
      <div><dt>Subtotal</dt><dd>₹3,840</dd></div>
      <div><dt>Delivery</dt><dd>Free</dd></div>
      <div class="ap-dlist__total"><dt>Total</dt><dd>₹3,840</dd></div>
    </dl>
  </section>

  <section class="ap-dlist__card" aria-labelledby="dlist-profile">
    <div class="ap-dlist__top">
      <h3 class="ap-dlist__name" id="dlist-profile">Profile</h3>
      <p class="ap-dlist__sub">Your account details</p>
    </div>
    <dl class="ap-dlist__list">
      <div class="ap-dlist__row">
        <dt>Name</dt>
        <dd>Asha Rao</dd>
        <dd class="ap-dlist__act"><a class="ap-dlist__edit" href="#edit-name">Edit<span class="ap-dlist__sr"> name</span></a></dd>
      </div>
      <div class="ap-dlist__row">
        <dt>Email</dt>
        <dd>[email protected]</dd>
        <dd class="ap-dlist__act"><a class="ap-dlist__edit" href="#edit-email">Edit<span class="ap-dlist__sr"> email</span></a></dd>
      </div>
      <div class="ap-dlist__row">
        <dt>Phone</dt>
        <dd>+91 98765 43210</dd>
        <dd class="ap-dlist__act"><a class="ap-dlist__edit" href="#edit-phone">Edit<span class="ap-dlist__sr"> phone number</span></a></dd>
      </div>
      <div class="ap-dlist__row">
        <dt>Languages</dt>
        <dd>English</dd>
        <dd>Hindi</dd>
        <dd>Kannada</dd>
        <dd class="ap-dlist__act"><a class="ap-dlist__edit" href="#edit-languages">Edit<span class="ap-dlist__sr"> languages</span></a></dd>
      </div>
      <div class="ap-dlist__row">
        <dt>Member since</dt>
        <dd>March 2021</dd>
      </div>
    </dl>
  </section>

  <section class="ap-dlist__card ap-dlist__card--wide" aria-labelledby="dlist-which">
    <div class="ap-dlist__top">
      <h3 class="ap-dlist__name" id="dlist-which">Which element to use</h3>
    </div>
    <dl class="ap-dlist__compare">
      <div>
        <dt>Description list <code class="ap-dlist__code" translate="no">&lt;dl&gt;</code></dt>
        <dd>Names and values about one thing, like this order or this profile.</dd>
      </div>
      <div>
        <dt>Table <code class="ap-dlist__code" translate="no">&lt;table&gt;</code></dt>
        <dd>The same fields for many things, read across and down, like all your orders.</dd>
      </div>
      <div>
        <dt>List <code class="ap-dlist__code" translate="no">&lt;ul&gt;</code></dt>
        <dd>Items of one kind with no labels, like the products in a basket.</dd>
      </div>
    </dl>
  </section>

  <p class="ap-dlist__status" role="status"></p>
</div>

WCAG 2.2

What it meets

The success criteria this pattern takes care of, and how.

  • 1.3.1 Info and Relationships Level A

    dt and dd tie each label to its values in the markup, so the pairing survives without the two-column layout.

  • 1.3.2 Meaningful Sequence Level A

    Each term comes before its values in the source, and the stacked layout keeps that order on screen.

  • 1.4.10 Reflow Level AA

    Rows switch from label beside value to label above value in a narrow space, so nothing scrolls sideways at 320 pixels.

  • 2.4.4 Link Purpose (In Context) Level A

    Every Edit link's name says what it edits, like "Edit shipping address", so it makes sense in a list of links.

  • 2.4.7 Focus Visible Level AA

    The Edit links show a two-pixel focus ring.

  • 2.5.8 Target Size (Minimum) Level AA

    Each Edit link is at least 24 pixels tall and set apart from its neighbours.

Usage

When to use it

Use it

  • Names and values about one thing: an order summary, a profile, a file's properties, a product's specifications.
  • Glossaries and FAQs where each term has one or more descriptions.

Use something else

  • The same fields for many records: a table lets people compare down a column.
  • Items of one kind with no labels: a ul or ol says that more simply.
  • Layout: don't use dl just to get two columns of unrelated text.

Common failures

How it usually goes wrong

  • Labels and values in plain divs

    Two divs styled as columns look paired but are read as unrelated text. dt and dd make the pairing part of the markup.

  • A row of Edit links with the same name

    Five links called "Edit" mean nothing in a list of links. Hidden text completes each one: Edit shipping address, Edit phone number.

  • Invalid wrappers inside dl

    HTML lets a dl hold dt and dd, or divs that each hold them. A span, a section or a stray p breaks the list for some screen readers.

  • One value split into many dd elements

    An address broken into four dd elements is announced as four separate values. Use several dd elements only when there really are several values.

  • Empty values left blank

    A term with an empty dd sounds like a mistake. Say "Not added" or leave the pair out.

Notes

Building it

  • Wrap each dt and dd group in a div to style it as a row; a dl may contain divs that hold only dt and dd elements.
  • A term can have several dd elements, as Languages does here, and several dt elements can share one description.
  • The Edit links sit in their own dd, as in the GOV.UK summary list, because a div inside a dl may hold only dt and dd.
  • Screen readers vary on dl: some announce it as a list with the number of groups, others just read the text. The pairing still holds in each case.
  • The Edit links use #… addresses because they stand for other pages; the script only keeps them on this page. A description list needs no script.

Sources: HTML: the dl element · GOV.UK Design System: Summary list · WCAG 2.2 Understanding: Link Purpose (In Context)

Checked with axe in light and dark themes, at desktop and phone widths, and by keyboard. Not yet tested with every screen reader and browser pair. Report a correction

Related

  • Lists and groups

    Bulleted, numbered and description lists that announce their size, even when styled as cards, tags or numbered steps.

    4 WCAG criteria2 keyboard rules

  • Sortable table

    A data table with a caption, row headers, sort buttons that report the order, and row selection with a mixed Select all.

    7 WCAG criteria4 keyboard rules

  • Card

    Cards whose title link covers the whole card, with Save and Share buttons that stay reachable on top of it.

    7 WCAG criteria3 keyboard rules

  • Visually hidden text

    Text that screen readers read but the screen does not show, hidden the one way that keeps it in the accessibility tree.

    7 WCAG criteria4 keyboard rules