Description list

When to use

Reach for a description list to show the properties of one object, where each value is read with its label: a product's specifications, an order's details, a profile's contact information. To compare several objects across the same properties, use a table instead.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/description-list.js";

<eun-description-list>
  <dl>
    <dt>Name</dt>
    <dd>Single lever basin mixer</dd>
    <dt>Reference</dt>
    <dd>GRO-MC-001-CHR</dd>
  </dl>
</eun-description-list>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/description-list.js";
</script>

<eun-description-list>
  <dl>
    <dt>Name</dt>
    <dd>Single lever basin mixer</dd>
    <dt>Reference</dt>
    <dd>GRO-MC-001-CHR</dd>
  </dl>
</eun-description-list>

npm install @eunomia/elements

import "@eunomia/elements/description-list.js";

function ProductDetails({ product }) {
  return (
    <eun-description-list>
      <dl>
        <dt>Name</dt>
        <dd>{product.name}</dd>
        <dt>Reference</dt>
        <dd>{product.reference}</dd>
      </dl>
    </eun-description-list>
  );
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/description-list.js";

export function ProductDetails({ product }) {
  return (
    <eun-description-list>
      <dl>
        <dt>Name</dt>
        <dd>{product.name}</dd>
        <dt>Reference</dt>
        <dd>{product.reference}</dd>
      </dl>
    </eun-description-list>
  );
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/description-list.js";
  defineProps(["product"]);
</script>

<template>
  <eun-description-list>
    <dl>
      <dt>Name</dt>
      <dd>{{ product.name }}</dd>
      <dt>Reference</dt>
      <dd>{{ product.reference }}</dd>
    </dl>
  </eun-description-list>
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component, input } from "@angular/core";
import "@eunomia/elements/description-list.js";

@Component({
  selector: "app-product-details",
  template: `
    <eun-description-list>
      <dl>
        <dt>Name</dt>
        <dd>{{ product().name }}</dd>
        <dt>Reference</dt>
        <dd>{{ product().reference }}</dd>
      </dl>
    </eun-description-list>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class ProductDetailsComponent {
  product = input.required<{ name: string; reference: string }>();
}

Server rendering

eun-description-list has no shadow root: one stylesheet holds its whole style. Link description-list-ssr.css to have a server-rendered list look final before the component loads.

<link
  rel="stylesheet"
  href="node_modules/@eunomia/elements/dist/ssr/description-list-ssr.css"
/>

import "@eunomia/elements/description-list-ssr.css";

Responsive behavior

Below 600px, the label moves above its value, since a narrow screen leaves too little room for both on one line, and the pairs fill a single column whatever columns is set to.

Alternatives

Guidance

Live testing

Properties

Markup conventions

Place a native <dl> directly inside <eun-description-list>. Each pair is a <dt> holding the label, followed by one or more <dd> holding its values. HTML also allows wrapping each pair in a <div>, which columns requires.

<eun-description-list>
  <dl>
    <dt>Label</dt>
    <dd>Value</dd>
  </dl>
</eun-description-list>

Layout

Inline

The default layout. Each label sits beside its value, in a column sized to the longest label, up to 40% of the list's width.

<eun-description-list>
  <dl>
    <dt>Name</dt>
    <dd>Single lever basin mixer</dd>
    <dt>Reference</dt>
    <dd>GRO-MC-001-CHR</dd>
    <dt>Last updated</dt>
    <dd>October 9, 2026</dd>
  </dl>
</eun-description-list>

Stacked

layout="stacked" places each label above its value, which suits long values or a narrow container.

<eun-description-list layout="stacked">
  <dl>
    <dt>Delivery address</dt>
    <dd>12 avenue Jean Jaurès, 30100 Alès</dd>
    <dt>Instructions</dt>
    <dd>Leave the parcel at the store counter if nobody answers.</dd>
  </dl>
</eun-description-list>

Columns

columns lays the pairs out in up to 4 columns from 600px up, each pair wrapped in a <div>. Below 600px, they fill a single column. With divided, a line runs between two rows, never above the first one.

<eun-description-list columns="2" layout="stacked" divided>
  <dl>
    <div>
      <dt>Storage</dt>
      <dd>150 m²</dd>
    </div>
    <div>
      <dt>Items in stock</dt>
      <dd>3,000+</dd>
    </div>
    <div>
      <dt>Showroom</dt>
      <dd>Bathroom and sanitary ware</dd>
    </div>
    <div>
      <dt>After-sales</dt>
      <dd>Spare parts available</dd>
    </div>
  </dl>
</eun-description-list>

Alignment

align aligns the text of the labels and values: start by default, center, or end. align="space-between" keeps each label at the start and pushes its value to the end, when the label sits beside it.

<eun-description-list align="space-between" divided>
  <dl>
    <dt>Subtotal</dt>
    <dd>€220.00</dd>
    <dt>Shipping</dt>
    <dd>€28.90</dd>
    <dt>Total</dt>
    <dd>€248.90</dd>
  </dl>
</eun-description-list>

align="center" suits key figures laid out in columns.

<eun-description-list columns="3" layout="stacked" align="center">
  <dl>
    <div>
      <dt>Storage</dt>
      <dd>150 m²</dd>
    </div>
    <div>
      <dt>Items in stock</dt>
      <dd>3,000+</dd>
    </div>
    <div>
      <dt>Founded</dt>
      <dd>1978</dd>
    </div>
  </dl>
</eun-description-list>

Divided

divided draws a line between two pairs.

<eun-description-list divided>
  <dl>
    <dt>Order</dt>
    <dd>#20461</dd>
    <dt>Status</dt>
    <dd>Shipped</dd>
    <dt>Total</dt>
    <dd>€248.90</dd>
  </dl>
</eun-description-list>

Several values

A label followed by several <dd> lists each value on its own line. A value holds any content, such as a link or a tag.

<eun-description-list>
  <dl>
    <dt>Finishes</dt>
    <dd><eun-tag size="s">Chrome</eun-tag></dd>
    <dd><eun-tag size="s">Brushed nickel</eun-tag></dd>
    <dt>Data sheets</dt>
    <dd><eun-link href="/guide.pdf">Installation guide</eun-link></dd>
    <dd><eun-link href="/parts.pdf">Spare parts</eun-link></dd>
  </dl>
</eun-description-list>

Custom appearance

Every color, size, and space is a CSS custom property, listed in the API tab.

eun-description-list {
  --description-list-label-width: 10rem;
  --description-list-label-font-weight: 600;
  --description-list-label-color: var(--eun-color-primary-500);
  --description-list-row-gap: 0.5rem;
}

A class on your own <dt> or <dd> overrides the list's rules too, since they stay at a low specificity.

Native semantics

eun-description-list has no shadow root, no item component and no ARIA role of its own: assistive technology meets the native <dl>, its terms and its definitions, exactly as authored. Most screen readers announce it as a list, and read each value right after its label. A <div> wrapping a pair adds nothing to the accessibility tree.

The layout only changes how the pairs look. The reading order stays the order of the markup, a label always before its values, whatever layout or columns is set.

Naming the list

A description list has no accessible name, and an aria-label on the <dl> isn't reliably announced. When a page holds several, place a heading right above each one, which screen reader users can also jump to:

<h2>Specifications</h2>
<eun-description-list>
  <dl>
    <dt>Reference</dt>
    <dd>GRO-MC-001-CHR</dd>
  </dl>
</eun-description-list>

Non-focusable

The list itself isn't focusable. Links and buttons placed in a value stay in the tab order, in the order of the markup.

Reference links

MDN: the <dl> element