Description lists need only terms and descriptions

• Rule: axe/definition-list
• Checks: <dl> elements must only directly contain properly-ordered <dt> and <dd> groups, <script>, <template> or <div> elements
• WCAG: 1.3.1
• Fix class: mechanical: A fix needs no authored text or visual decision.

Who it affects

• People who use a screen reader or a braille display, most of them blind.

How to fix it

A <dl> holds other elements or text directly, such as a <p> or a heading

Keep only <dt> and <dd> elements in the <dl>, or one <div> around each group of them. Move other content before or after the list.

<dl>
  <dt>Plan</dt>
  <dd>Team</dd>
  <dt>Renews</dt>
  <dd>March 1</dd>
</dl>

Each group of terms and descriptions is wrapped in a <span>, a nested <div> or a <div> with a role

Wrap each group in a single plain <div> that is a direct child of the <dl>.

<dl>
  <div>
    <dt>Plan</dt>
    <dd>Team</dd>
  </div>
  <div>
    <dt>Renews</dt>
    <dd>March 1</dd>
  </div>
</dl>

The list has no <dt> followed by a <dd>, such as only terms, only descriptions, or descriptions before their terms

Start each group with its <dt> and follow it with its <dd>. If the content is not pairs of terms and descriptions, use a <ul> or paragraphs instead.

Fixes that fail

Rebuilding the list from <div> and <span> elements to clear the rule

axe stops reporting it, but nothing then ties each term to its description for screen reader users.

In React

The part of the fix that differs in React, in its syntax. The rest of the guidance holds.

A component for one term and its description returns them in a <div>, and its caller wraps it in another

Give each group exactly one plain <div>, added by the component or by its caller, not both. A component that returns a fragment leaves the choice to its caller.

function Detail({ term, children }) {
  return (
    <div>
      <dt>{term}</dt>
      <dd>{children}</dd>
    </div>
  );
}

function OrderSummary({ order }) {
  return (
    <dl>
      <Detail term="Order number">{order.number}</Detail>
      <Detail term="Status">{order.status}</Detail>
    </dl>
  );
}

A <div> wraps each mapped group only to hold its key

Put the key on the component instead, or use <Fragment key={…}>, which adds no element.

More on the rule

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.