Description List

c2-description-list

Read-only key/value pairs for a detail page: the Descriptions of antd and the DescriptionList of Polaris. Each c2-description-item child is one pair. The items flow into as many columns as fit, up to --c2-description-list__grid--columns, each at least --c2-description-list__grid--min-column-width wide, so the same markup is three columns on a wide page and one on a phone without a media query. An item spans the full row with --c2-description-item--grid-column: 1 / -1.

Whether a label sits above its value or beside it is CSS too: --c2-description-item__label--width set to a length puts the label beside the value, and the value still wraps under it when the item is narrower than the label plus --c2-description-item__value--min-width. Set the item variables on the list and every item inherits them.

Items with several values (c2-description-value children) line up in columns; value-labels names those columns in a header row and label-heading heads the label column. Style the row through --c2-description-list__value-header--* (or the value-header part), or hide it with --c2-description-list__value-header--display: none. The header hides itself when the values stack, and each value then shows its column name. A list with value columns lays its items out in a single column.

The list is exposed as a list and every item as a listitem holding a term and its definition.

<c2-description-list aria-label="Customer">
  <c2-description-item label="Name">Ada Lovelace</c2-description-item>
  <c2-description-item label="Email">ada@example.com</c2-description-item>
  <c2-description-item label="Plan">Business</c2-description-item>
</c2-description-list>

c2-description-item

One label and value pair of a c2-description-list. The label comes from the label attribute, or from the label slot when it needs markup (an icon, a tooltip); the value is the item's content, which can be anything from plain text to a badge, a link or an avatar. An item with no value shows empty-text, so a missing field reads as "—" instead of an empty gap.

An item can hold several values, one c2-description-value each: the price of a feature in each plan, a metric this month and last. They line up in equal columns across the items of the list, and the list's value-labels names those columns. The layout adapts on its own: when the label and the columns no longer fit on one line the columns move under the label, and when the columns themselves no longer fit (each narrower than --c2-description-item__value-column--min-width) the values stack, each with its column name as a caption.

c2-description-value

One value of a c2-description-item that has several, such as a plan's price in each of three plans. Values line up in columns across the items of a list, and the list's value-labels names the columns. When the columns no longer fit, the values stack under their label and each one shows its column name as a caption; the caption is always there for assistive technology, which reads it with the value.