XDS — Design System

XDSMetadataList@xds/core · MetadataList

Usage

MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.

Best practices

Guidance	Practices
Do	Choose label position based on content — "start" for short values, "top" for long or complex values.
Do	Collapse long lists with `maxNumOfItems` to keep the page scannable.
Don't	Use for extensive form input — use a form layout instead.
Don't	Use for data that doesn't have a clear key-value structure.

Anatomy

Element		Description
Title		Optional title for the metadata list.
Label	required	The key label for each metadata entry.
Metadata	required	The value displayed in various formats.
Disclosure		Collapse/expand control for the list.

Import

ts
import {XDSMetadataList} from '@xds/core/MetadataList'

Props

Prop	Type	Description
childrenrequired	ReactNode	Metadata items (XDSMetadataListItem components).
columns	'multi' \| 'single' \| number (default: 'single')	Column layout mode.
label	{ position?: 'start' \| 'top', width?: number \| string } (default: { position: 'start' } (single-column) / { position: 'top' } (multi-column))	Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts.
maxNumOfItems	number	Maximum items to show before collapsing with a show more/less toggle.
orientation	'vertical' \| 'horizontal' (default: 'vertical')	Layout orientation. Horizontal mode flows items in a row with flex-wrap.
title	ReactNode	Optional title or heading above the list.
xstyle	StyleXStyles	StyleX styles for layout customization. Must be a stylex.create() value.

Sub-components

MetadataList is a compound component with 2 sub-components.

XDSMetadataList

Container for metadata items with column layout, orientation, and collapse support.

Prop	Type	Description
childrenrequired	ReactNode	Metadata items (XDSMetadataListItem components).
columns	'multi' \| 'single' \| number (default: 'single')	Column layout mode.
label	{ position?: 'start' \| 'top', width?: number \| string } (default: { position: 'start' } (single-column) / { position: 'top' } (multi-column))	Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts.
maxNumOfItems	number	Maximum items to show before collapsing with a show more/less toggle.
orientation	'vertical' \| 'horizontal' (default: 'vertical')	Layout orientation. Horizontal mode flows items in a row with flex-wrap.
title	ReactNode	Optional title or heading above the list.
xstyle	StyleXStyles	StyleX styles for layout customization. Must be a stylex.create() value.

XDSMetadataListItem

A single labeled metadata value within an XDSMetadataList.

Prop	Type	Description
childrenrequired	ReactNode	Content value for this metadata item.
labelrequired	string	Label text for this metadata item.
icon	ReactNode	Icon rendered before the label text.

Examples

Common configurations, variations, and states.

MetadataList — BasicSingle-column key-value metadata list.

tsx
'use client';
import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
export default function MetadataListBasicMetadata() {
  return (
    <XDSMetadataList>
      <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
      <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
      <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
    </XDSMetadataList>
  );
}

MetadataList — CollapsibleMetadata list with a show-more toggle after a set number of items.

tsx
'use client';
import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
export default function MetadataListCollapsibleMetadata() {
  return (
    <XDSMetadataList maxNumOfItems={3}>
      <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
      <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
      <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
      <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>
      <XDSMetadataListItem label="Updated">Mar 26, 2026</XDSMetadataListItem>
      <XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>
    </XDSMetadataList>
  );
}

MetadataList — HorizontalHorizontal metadata items for compact inline display.

tsx
'use client';
import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
export default function MetadataListHorizontalMetadata() {
  return (
    <XDSMetadataList orientation="horizontal">
      <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
      <XDSMetadataListItem label="Type">Premium</XDSMetadataListItem>
      <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
      <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>
    </XDSMetadataList>
  );
}

MetadataList — Multi-ColumnMulti-column metadata grid with token tags.

tsx
'use client';
import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
import {XDSToken} from '@xds/core/Token';
import {XDSHStack} from '@xds/core/Layout';
export default function MetadataListMultiColumnMetadata() {
  return (
    <XDSMetadataList columns="multi">
      <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
      <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
      <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
      <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>
      <XDSMetadataListItem label="Tags">
        <XDSHStack gap={1}>
          <XDSToken label="component" />
          <XDSToken label="xds" />
        </XDSHStack>
      </XDSMetadataListItem>
      <XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>
    </XDSMetadataList>
  );
}

Showcase source

tsx
'use client';
import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
export default function MetadataListShowcase() {
  return (
    <XDSMetadataList>
      <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
      <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
      <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
    </XDSMetadataList>
  );
}