Terms and descriptions need to sit in a description list

• Rule: axe/dlitem
• Checks: <dt> and <dd> elements must be contained by a <dl>
• 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

The <dt> and <dd> elements sit in a <div>, a list item or another container

Wrap them in a <dl>. One plain <div> around each group, directly inside the <dl>, is also allowed.

<dl>
  <dt>Order number</dt>
  <dd>48213</dd>
  <dt>Status</dt>
  <dd>Shipped</dd>
</dl>

The groups are wrapped twice, such as a <div> inside a <div>, or wrapped in a <span>

Use a single plain <div> around each group, as a direct child of the <dl>.

The <dl> has a role, such as role="group"

Remove the role from the <dl>.

Fixes that fail

Replacing <dt> and <dd> with styled <div> elements

axe stops reporting them, 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 that returns a <dt> and a <dd> is rendered outside a <dl>

Render it only inside a <dl>, or have the component that lists the groups render the <dl> around them.

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

function ShippingDetails() {
  return (
    <dl>
      <Detail term="Carrier">Acme Post</Detail>
      <Detail term="Arrives">May 4</Detail>
    </dl>
  );
}

The groups end up wrapped twice, by the component and by its caller

Keep one plain <div> per group: let the component or its caller add it, not both.

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.