Description List
Structured term/detail pair list in a responsive grid layout with optional dividers.
<arc-description-list>Overview
DescriptionList renders term/detail pairs in a grid layout for metadata displays, specification tables, and detail panels. Each child arc-description-item contains a term label and a detail slot, with the term displayed as an uppercase accent label and the detail rendered below it.
Two props control arrangement and they are about different axes. columns is how many items sit across; set it to 2, 3, or 4 to arrange pairs side by side. layout is how each item arranges its own term and detail: stacked (the default) puts the term above the detail, and horizontal puts them side by side on a shared two-column grid so terms align down the list. They compose: one item can be horizontal inside a three-column list. Vertical dividers appear automatically between columns when dividers is enabled, and on screens narrower than 640px the grid collapses to a single column for readability.
layout arrived with arc-key-value, which merged in here in v4. A term beside its detail was that component's whole reason to exist as a separate element, so absorbing it meant absorbing the arrangement. One thing to watch when migrating: Key Value defaulted to the horizontal arrangement and this component defaults to stacked, so add layout="horizontal" to keep what you had. The survivor's default stays unchanged, because a merge is not the place to restyle the component that survived. See the tombstone for the full translation.
Dividers (bottom borders between items, and right borders between columns) are enabled by default and can be toggled off with the dividers attribute. The container uses role="list" and each item uses role="listitem" for assistive technology support.
Guidelines
When to use
- Use for structured key/value metadata such as profile details, order summaries, or spec sheets
- Set `columns` to 2 or 3 for wider layouts where items are short and scannable
- Use `layout="horizontal"` when terms are short and you want them to align down a single column of pairs
- Pair with cards or panels for contained metadata displays
- Keep term labels concise. One to three words is ideal
When not to use
- Do not use for tabular data with many rows. Use `arc-data-grid` instead
- Do not nest description lists inside each other
- Do not combine `layout="horizontal"` with a high `columns` count. Each item then needs room for two columns of its own, and both collapse to nothing
- Do not use long paragraph-length terms. Move verbose content to the detail slot
- Do not mix description items with non-`arc-description-item` children
Features
- ARIA list/listitem roles for assistive technology support
- Responsive grid layout with configurable column count
- `layout="horizontal"` puts each term beside its detail on a shared grid, so terms align down the list
- Automatic single-column fallback below 640px
- Optional horizontal and vertical dividers between items
- Uppercase accent-font term labels for visual hierarchy
- CSS parts: `list`, `item`, `term`, `detail` for deep customization
- Follows `prefers-reduced-motion` for reduced-motion users
Preview
Name
Status
Region
Version
Name
Status
Region
Usage
<arc-description-list columns="2">
<arc-description-item term="Name">Arclight Platform</arc-description-item>
<arc-description-item term="Status">Active</arc-description-item>
<arc-description-item term="Region">US-West-2</arc-description-item>
<arc-description-item term="Version">4.2.1</arc-description-item>
</arc-description-list>
<!-- Term beside detail. This is what arc-key-value defaulted to. -->
<arc-description-list layout="horizontal">
<arc-description-item term="Name">Arclight Platform</arc-description-item>
<arc-description-item term="Status">Active</arc-description-item>
</arc-description-list>import { DescriptionList, DescriptionItem } from '@arclux/arc-ui-react';
export default function Example() {
return (
<DescriptionList columns={2}>
<DescriptionItem term="Name">Arclight Platform</DescriptionItem>
<DescriptionItem term="Status">Active</DescriptionItem>
<DescriptionItem term="Region">US-West-2</DescriptionItem>
<DescriptionItem term="Version">4.2.1</DescriptionItem>
</DescriptionList>
);
}<script setup>
import { DescriptionList, DescriptionItem } from '@arclux/arc-ui-vue';
</script>
<template>
<DescriptionList :columns="2">
<DescriptionItem term="Name">Arclight Platform</DescriptionItem>
<DescriptionItem term="Status">Active</DescriptionItem>
<DescriptionItem term="Region">US-West-2</DescriptionItem>
<DescriptionItem term="Version">4.2.1</DescriptionItem>
</DescriptionList>
</template><script>
import { DescriptionList, DescriptionItem } from '@arclux/arc-ui-svelte';
</script>
<DescriptionList columns={2}>
<DescriptionItem term="Name">Arclight Platform</DescriptionItem>
<DescriptionItem term="Status">Active</DescriptionItem>
<DescriptionItem term="Region">US-West-2</DescriptionItem>
<DescriptionItem term="Version">4.2.1</DescriptionItem>
</DescriptionList>import { Component } from '@angular/core';
import { DescriptionList, DescriptionItem } from '@arclux/arc-ui-angular';
@Component({
imports: [DescriptionList, DescriptionItem],
template: `
<arc-description-list [columns]="2">
<arc-description-item term="Name">Arclight Platform</arc-description-item>
<arc-description-item term="Status">Active</arc-description-item>
<arc-description-item term="Region">US-West-2</arc-description-item>
<arc-description-item term="Version">4.2.1</arc-description-item>
</arc-description-list>
`,
})
export class MetadataComponent {}import { DescriptionList, DescriptionItem } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<DescriptionList columns={2}>
<DescriptionItem term="Name">Arclight Platform</DescriptionItem>
<DescriptionItem term="Status">Active</DescriptionItem>
<DescriptionItem term="Region">US-West-2</DescriptionItem>
<DescriptionItem term="Version">4.2.1</DescriptionItem>
</DescriptionList>
);
}import { DescriptionList, DescriptionItem } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<DescriptionList columns={2}>
<DescriptionItem term="Name">Arclight Platform</DescriptionItem>
<DescriptionItem term="Status">Active</DescriptionItem>
<DescriptionItem term="Region">US-West-2</DescriptionItem>
<DescriptionItem term="Version">4.2.1</DescriptionItem>
</DescriptionList>
);
}API
columnsnumber1- Number of grid columns for laying out items side by side.
layout'stacked' | 'horizontal''stacked'- How each item arranges its own term and detail.
stacked(the default) puts the term above the detail;horizontalputs them side by side on a shared two-column grid, so terms align down the list. This composes withcolumns, which is about how many *items* sit across. One item can be horizontal inside a three-column list. dividersbooleantrue- Show horizontal dividers between rows and vertical dividers between columns.
Description Item
<arc-description-item>A single term/detail pair within a description list. The term is rendered as an uppercase label, and the default slot holds the detail content.
termstring''- The key or label for this description entry, displayed as an uppercase heading.
See Also
- Data GridA spreadsheet-grade grid for working with tabular data: inline cell editing, multi-column sorting, pinned columns, row selection, and virtualized rendering. Columns are defined as a JavaScript array, and the grid implements the full WAI-ARIA grid keyboard pattern with a single tab stop.
- ListStructured list container with optional selection, keyboard navigation, and multiple visual variants. Pairs with arc-list-item for rich content rows.