Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

metadata list (#931)

Andrey Goder47cc726b18a3
diff --git a/apps/storybook/stories/MetadataList.stories.tsx b/apps/storybook/stories/MetadataList.stories.tsx
new file mode 100644
index 0000000000..f3f1304063
--- /dev/null
+++ b/apps/storybook/stories/MetadataList.stories.tsx
@@ -0,0 +1,171 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSToken} from '@xds/core/Token';
+import {
+ InformationCircleIcon,
+ CalendarIcon,
+ TagIcon,
+} from '@heroicons/react/24/outline';
+
+const meta: Meta<typeof XDSMetadataList> = {
+ title: 'Core/XDSMetadataList',
+ component: XDSMetadataList,
+ tags: ['autodocs'],
+ argTypes: {
+ columns: {
+ control: 'select',
+ options: ['single', 'multi', 2, 3],
+ description: 'Column layout mode',
+ },
+ orientation: {
+ control: 'select',
+ options: ['vertical', 'horizontal'],
+ description: 'Layout orientation',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSMetadataList>;
+
+export const Basic: Story = {
+ render: args => (
+ <XDSMetadataList {...args}>
+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const MultiColumn: Story = {
+ render: args => (
+ <XDSMetadataList columns="multi" {...args}>
+ <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">
+ <span style={{display: 'flex', gap: 4}}>
+ <XDSToken label="component" />
+ <XDSToken label="xds" />
+ </span>
+ </XDSMetadataListItem>
+ <XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const WithTitle: Story = {
+ render: args => (
+ <XDSMetadataList
+ title={<strong>Component Details</strong>}
+ columns="multi"
+ {...args}>
+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const Horizontal: Story = {
+ render: args => (
+ <XDSMetadataList orientation="horizontal" {...args}>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Type">Premium</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const StackedLabelsSingleColumn: Story = {
+ render: args => (
+ <XDSMetadataList label={{position: 'top'}} {...args}>
+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+ <XDSMetadataListItem label="Tags">
+ <span style={{display: 'flex', gap: 4}}>
+ <XDSToken label="component" />
+ <XDSToken label="xds" />
+ </span>
+ </XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const ShowMore: Story = {
+ render: args => (
+ <XDSMetadataList maxNumOfItems={3} {...args}>
+ <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>
+ ),
+};
+
+export const TwoColumns: Story = {
+ render: args => (
+ <XDSMetadataList columns={2} {...args}>
+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+ <XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const CustomLabelWidth: Story = {
+ render: args => (
+ <XDSMetadataList label={{position: 'start', width: 200}} {...args}>
+ <XDSMetadataListItem label="Full Name">
+ XDSMetadataList Component
+ </XDSMetadataListItem>
+ <XDSMetadataListItem label="Current Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Primary Owner">Joey</XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const MultiColumnSideLabels: Story = {
+ render: args => (
+ <XDSMetadataList columns="multi" label={{position: 'start'}} {...args}>
+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
+
+export const WithIcons: Story = {
+ render: args => (
+ <XDSMetadataList columns="multi" {...args}>
+ <XDSMetadataListItem
+ label="Information"
+ icon={<XDSIcon icon={InformationCircleIcon} size="sm" />}>
+ Important details about this component
+ </XDSMetadataListItem>
+ <XDSMetadataListItem
+ label="Created"
+ icon={<XDSIcon icon={CalendarIcon} size="sm" />}>
+ January 1, 2023
+ </XDSMetadataListItem>
+ <XDSMetadataListItem
+ label="Tags"
+ icon={<XDSIcon icon={TagIcon} size="sm" />}>
+ <span style={{display: 'flex', gap: 4}}>
+ <XDSToken label="component" />
+ <XDSToken label="xds" />
+ </span>
+ </XDSMetadataListItem>
+ </XDSMetadataList>
+ ),
+};
diff --git a/packages/core/package.json b/packages/core/package.json
index 9857b87447..12b69d03f9 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -190,6 +190,12 @@
"import": "./dist/List/index.mjs",
"require": "./dist/List/index.js"
},
+ "./MetadataList": {
+ "source": "./src/MetadataList/index.ts",
+ "types": "./dist/MetadataList/index.d.ts",
+ "import": "./dist/MetadataList/index.mjs",
+ "require": "./dist/MetadataList/index.js"
+ },
"./MobileNav": {
"source": "./src/MobileNav/index.ts",
"types": "./dist/MobileNav/index.d.ts",
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
new file mode 100644
index 0000000000..80e476d540
--- /dev/null
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -0,0 +1,159 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'MetadataList',
+ description:
+ 'A read-only labeled list for displaying key-value metadata. Semantic equivalent of HTML <dl>/<dt>/<dd> with layout control, column modes, and consistent styling. Uses a composition model: XDSMetadataList wraps XDSMetadataListItem sub-components.',
+ features: [
+ 'Composition model — XDSMetadataList wraps XDSMetadataListItem sub-components',
+ 'Column modes: single, multi (auto-fill), or fixed number',
+ 'Label positioning: start (side-by-side) or top (stacked)',
+ 'Horizontal orientation with flex-wrap',
+ 'Show more / show less toggle when items exceed maxNumOfItems',
+ 'Optional title heading above the list',
+ 'Optional icon before label text',
+ 'Semantic <dl>/<dt>/<dd> HTML structure',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSMetadataList>
+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+</XDSMetadataList>`,
+ },
+ {
+ label: 'Multi-column',
+ code: `<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>
+</XDSMetadataList>`,
+ },
+ {
+ label: 'Horizontal',
+ code: `<XDSMetadataList orientation="horizontal">
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Type">Premium</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+</XDSMetadataList>`,
+ },
+ {
+ label: 'With title and show more',
+ code: `<XDSMetadataList title={<XDSHeading type="header4">Details</XDSHeading>} maxNumOfItems={3}>
+ <XDSMetadataListItem label="Name">Value</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>
+ <XDSMetadataListItem label="Created">Jan 2026</XDSMetadataListItem>
+ <XDSMetadataListItem label="Updated">Mar 2026</XDSMetadataListItem>
+</XDSMetadataList>`,
+ },
+ ],
+ accessibility: [
+ 'Semantic <dl> with <dt>/<dd> pairs',
+ 'aria-controls links the show more/less button to the list',
+ 'aria-expanded indicates whether the list is fully expanded',
+ ],
+ theming: {
+ targets: [
+ {
+ className: 'xds-metadata-list',
+ visualProps: ['columns', 'orientation'],
+ },
+ {className: 'xds-metadata-list-item'},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSMetadataList',
+ description:
+ 'Container for metadata items with column layout, orientation, and collapse support.',
+ examples: [
+ {
+ label: 'With title',
+ code: `<XDSMetadataList title={<strong>Details</strong>} columns="multi">
+ <XDSMetadataListItem label="Name">Value</XDSMetadataListItem>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+</XDSMetadataList>`,
+ },
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Metadata items (XDSMetadataListItem components).',
+ required: true,
+ },
+ {
+ name: 'columns',
+ type: "'multi' | 'single' | number",
+ description: 'Column layout mode.',
+ default: "'single'",
+ },
+ {
+ name: 'label',
+ type: "{ position?: 'start' | 'top', width?: number | string }",
+ description:
+ "Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts.",
+ default: "{ position: 'start' } (single-column) / { position: 'top' } (multi-column)",
+ },
+ {
+ name: 'maxNumOfItems',
+ type: 'number',
+ description:
+ 'Maximum items to show before collapsing with a show more/less toggle.',
+ },
+ {
+ name: 'orientation',
+ type: "'vertical' | 'horizontal'",
+ description:
+ 'Layout orientation. Horizontal mode flows items in a row with flex-wrap.',
+ default: "'vertical'",
+ },
+ {
+ name: 'title',
+ type: 'ReactNode',
+ description: 'Optional title or heading above the list.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+ },
+ {
+ name: 'XDSMetadataListItem',
+ description: 'A single labeled metadata value within an XDSMetadataList.',
+ examples: [
+ {
+ label: 'With icon',
+ code: `<XDSMetadataListItem label="Status" icon={<StatusIcon />}>
+ Active
+</XDSMetadataListItem>`,
+ },
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content value for this metadata item.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for this metadata item.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon rendered before the label text.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/MetadataList/XDSMetadataList.test.tsx b/packages/core/src/MetadataList/XDSMetadataList.test.tsx
new file mode 100644
index 0000000000..7bd8f2ff44
--- /dev/null
+++ b/packages/core/src/MetadataList/XDSMetadataList.test.tsx
@@ -0,0 +1,141 @@
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSMetadataList} from './XDSMetadataList';
+import {XDSMetadataListItem} from './XDSMetadataListItem';
+
+describe('XDSMetadataList', () => {
+ it('renders a description list with items', () => {
+ render(
+ <XDSMetadataList>
+ <XDSMetadataListItem label="Name">Alice</XDSMetadataListItem>
+ <XDSMetadataListItem label="Role">Engineer</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.getByText('Name')).toBeInTheDocument();
+ expect(screen.getByText('Alice')).toBeInTheDocument();
+ expect(screen.getByText('Role')).toBeInTheDocument();
+ expect(screen.getByText('Engineer')).toBeInTheDocument();
+ });
+
+ it('renders a semantic dl element', () => {
+ const {container} = render(
+ <XDSMetadataList>
+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(container.querySelector('dl')).toBeInTheDocument();
+ expect(container.querySelector('dt')).toBeInTheDocument();
+ expect(container.querySelector('dd')).toBeInTheDocument();
+ });
+
+ it('renders a title when provided', () => {
+ render(
+ <XDSMetadataList title={<h3>Details</h3>}>
+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.getByText('Details')).toBeInTheDocument();
+ });
+
+ it('supports data-testid', () => {
+ render(
+ <XDSMetadataList data-testid="my-list">
+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.getByTestId('my-list')).toBeInTheDocument();
+ });
+
+ it('shows "Show more" button when items exceed maxNumOfItems', () => {
+ render(
+ <XDSMetadataList maxNumOfItems={2}>
+ <XDSMetadataListItem label="A">1</XDSMetadataListItem>
+ <XDSMetadataListItem label="B">2</XDSMetadataListItem>
+ <XDSMetadataListItem label="C">3</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.getByText('Show more')).toBeInTheDocument();
+ // Third item should be hidden
+ expect(screen.queryByText('C')).not.toBeInTheDocument();
+ });
+
+ it('toggles show more / show less', async () => {
+ const user = userEvent.setup();
+
+ render(
+ <XDSMetadataList maxNumOfItems={1}>
+ <XDSMetadataListItem label="A">1</XDSMetadataListItem>
+ <XDSMetadataListItem label="B">2</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.queryByText('B')).not.toBeInTheDocument();
+
+ await user.click(screen.getByText('Show more'));
+ expect(screen.getByText('B')).toBeInTheDocument();
+ expect(screen.getByText('Show less')).toBeInTheDocument();
+
+ await user.click(screen.getByText('Show less'));
+ expect(screen.queryByText('B')).not.toBeInTheDocument();
+ });
+
+ it('does not show toggle in horizontal mode even with maxNumOfItems', () => {
+ render(
+ <XDSMetadataList orientation="horizontal" maxNumOfItems={1}>
+ <XDSMetadataListItem label="A">1</XDSMetadataListItem>
+ <XDSMetadataListItem label="B">2</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.queryByText('Show more')).not.toBeInTheDocument();
+ expect(screen.getByText('A')).toBeInTheDocument();
+ expect(screen.getByText('B')).toBeInTheDocument();
+ });
+});
+
+describe('XDSMetadataListItem', () => {
+ it('renders label and children', () => {
+ render(
+ <XDSMetadataList>
+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.getByText('Status')).toBeInTheDocument();
+ expect(screen.getByText('Active')).toBeInTheDocument();
+ });
+
+ it('renders an icon when provided', () => {
+ render(
+ <XDSMetadataList>
+ <XDSMetadataListItem
+ label="Info"
+ icon={<span data-testid="test-icon">*</span>}>
+ Details
+ </XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ expect(screen.getByTestId('test-icon')).toBeInTheDocument();
+ });
+
+ it('renders in stacked mode when label position is top', () => {
+ const {container} = render(
+ <XDSMetadataList label={{position: 'top'}}>
+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>
+ </XDSMetadataList>,
+ );
+
+ // In stacked mode, dt and dd are inside a wrapper div
+ const wrapper = container.querySelector('.xds-metadata-list-item');
+ expect(wrapper).toBeInTheDocument();
+ expect(wrapper?.querySelector('dt')).toBeInTheDocument();
+ expect(wrapper?.querySelector('dd')).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/MetadataList/XDSMetadataList.tsx b/packages/core/src/MetadataList/XDSMetadataList.tsx
new file mode 100644
index 0000000000..1904cbf023
--- /dev/null
+++ b/packages/core/src/MetadataList/XDSMetadataList.tsx
@@ -0,0 +1,296 @@
+'use client';
+
+/**
+ * @file XDSMetadataList.tsx
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, XDSMetadataListContext
+ * @output Exports XDSMetadataList component, XDSMetadataListProps, XDSMetadataListColumns types
+ * @position Core implementation; consumed by index.ts, tested by XDSMetadataList.test.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/MetadataList/MetadataList.doc.mjs
+ * - /packages/core/src/MetadataList/XDSMetadataList.test.tsx
+ * - /packages/core/src/MetadataList/index.ts
+ * - /apps/storybook/stories/MetadataList.stories.tsx
+ */
+
+import {Children, useId, useMemo, useState, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ spacingVars,
+ colorVars,
+ typeScaleVars,
+ fontWeightVars,
+} from '../theme/tokens.stylex';
+import {
+ XDSMetadataListContext,
+ type XDSMetadataListLabelConfig,
+} from './XDSMetadataListContext';
+import {xdsClassName, mergeProps} from '../utils';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type XDSMetadataListColumns = 'multi' | 'single' | number;
+
+export interface XDSMetadataListProps {
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+ /**
+ * Metadata list items. Should be XDSMetadataListItem components.
+ */
+ children: ReactNode;
+ /**
+ * Column layout mode.
+ * - 'single': Items in a single column
+ * - 'multi': Auto-fill columns based on available width
+ * - number: Fixed number of columns
+ * @default 'single'
+ */
+ columns?: XDSMetadataListColumns;
+ /**
+ * Label display configuration.
+ * - position: 'start' places labels to the left, 'top' stacks labels above content
+ * - width: Custom label width (number in px or CSS string)
+ *
+ * Defaults to `{ position: 'top' }` for multi-column layouts and
+ * `{ position: 'start' }` for single-column layouts.
+ */
+ label?: XDSMetadataListLabelConfig;
+ /**
+ * Maximum number of items to show before collapsing.
+ * When set and items exceed this count, a "Show more" / "Show less"
+ * toggle appears.
+ */
+ maxNumOfItems?: number;
+ /**
+ * Layout orientation for metadata items.
+ * - 'vertical': Items stack vertically (default)
+ * - 'horizontal': Items flow horizontally with flex-wrap
+ *
+ * In horizontal mode, items display with labels stacked above content
+ * and wrap to new lines as needed. The following props are ignored:
+ * `columns`, `label`, `maxNumOfItems`.
+ * @default 'vertical'
+ */
+ orientation?: 'vertical' | 'horizontal';
+ /**
+ * Optional title or heading rendered above the list.
+ */
+ title?: ReactNode;
+ /**
+ * StyleX styles created via `stylex.create()`.
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element.
+ */
+ style?: React.CSSProperties;
+ /**
+ * Test ID for testing frameworks.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ },
+ title: {
+ marginBottom: spacingVars['--spacing-3'],
+ },
+ // dl reset
+ dl: {
+ margin: 0,
+ padding: 0,
+ },
+ // Vertical orientation — grid layout for label-value pairs
+ gridSingle: {
+ display: 'grid',
+ gridTemplateColumns: 'auto 1fr',
+ gap: `${spacingVars['--spacing-2']} ${spacingVars['--spacing-4']}`,
+ alignItems: 'baseline',
+ },
+ gridMulti: {
+ display: 'grid',
+ gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))',
+ gap: spacingVars['--spacing-4'],
+ },
+ // Stacked labels (position: 'top') within a single-column layout
+ gridStackedSingle: {
+ display: 'grid',
+ gridTemplateColumns: '1fr',
+ gap: spacingVars['--spacing-3'],
+ },
+ gridStackedMulti: {
+ display: 'grid',
+ gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))',
+ gap: spacingVars['--spacing-4'],
+ },
+ // Horizontal orientation — flex row with wrapping
+ horizontal: {
+ display: 'flex',
+ flexDirection: 'row',
+ flexWrap: 'wrap',
+ gap: spacingVars['--spacing-4'],
+ },
+ // Show more/less button
+ toggleButton: {
+ appearance: 'none',
+ background: 'none',
+ border: 'none',
+ padding: `${spacingVars['--spacing-2']} 0`,
+ cursor: 'pointer',
+ color: colorVars['--color-accent'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ fontFamily: 'inherit',
+ textAlign: 'start',
+ alignSelf: 'flex-start',
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A read-only labeled list for displaying key-value metadata.
+ *
+ * Renders semantic `<dl>` / `<dt>` / `<dd>` elements. Supports multiple
+ * column layouts, horizontal orientation, and show more/less collapsing.
+ *
+ * @example
+ * ```
+ * <XDSMetadataList columns="multi">
+ * <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>
+ * <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ * </XDSMetadataList>
+ * ```
+ */
+const LABEL_START: XDSMetadataListLabelConfig = {position: 'start'};
+const LABEL_TOP: XDSMetadataListLabelConfig = {position: 'top'};
+
+export function XDSMetadataList({
+ children,
+ columns = 'single',
+ label,
+ maxNumOfItems,
+ orientation = 'vertical',
+ title,
+ xstyle,
+ className,
+ style,
+ 'data-testid': testId,
+ ref,
+}: XDSMetadataListProps) {
+ const isMultiColumn =
+ columns === 'multi' || (typeof columns === 'number' && columns > 1);
+ // Default to 'top' for multi-column and horizontal layouts since side labels
+ // don't work well when items are in separate grid cells.
+ const labelConfig = label ?? (isMultiColumn ? LABEL_TOP : LABEL_START);
+ const [isShowAll, setIsShowAll] = useState(false);
+ const contentId = useId();
+
+ const contextValue = useMemo(
+ () => ({
+ labelConfig: orientation === 'horizontal' ? LABEL_TOP : labelConfig,
+ orientation,
+ }),
+ [labelConfig, orientation],
+ );
+
+ const childrenArray = Children.toArray(children);
+ const isHorizontal = orientation === 'horizontal';
+
+ // In horizontal mode, ignore maxNumOfItems
+ const effectiveMax = isHorizontal ? undefined : maxNumOfItems;
+ const isExceedMax =
+ effectiveMax != null && childrenArray.length > effectiveMax;
+ const visibleChildren =
+ isExceedMax && !isShowAll
+ ? childrenArray.slice(0, effectiveMax)
+ : childrenArray;
+
+ const titleContent =
+ title != null ? <div {...stylex.props(styles.title)}>{title}</div> : null;
+
+ // Determine grid style based on columns and label position
+ const getGridStyle = () => {
+ if (isHorizontal) return styles.horizontal;
+ const isStacked = labelConfig.position === 'top';
+ if (isStacked) {
+ return columns === 'single' || columns === 1
+ ? styles.gridStackedSingle
+ : styles.gridStackedMulti;
+ }
+ // Labels on the left
+ if (columns === 'single' || columns === 1) {
+ return styles.gridSingle;
+ }
+ return styles.gridMulti;
+ };
+
+ // For numeric columns > 1 with side labels, use inline style for dynamic grid
+ const dynamicGridStyle =
+ !isHorizontal &&
+ labelConfig.position === 'start' &&
+ typeof columns === 'number' &&
+ columns > 1
+ ? {gridTemplateColumns: `repeat(${columns}, auto 1fr)`}
+ : !isHorizontal &&
+ labelConfig.position === 'start' &&
+ labelConfig.width != null
+ ? {
+ gridTemplateColumns: `${typeof labelConfig.width === 'number' ? `${labelConfig.width}px` : labelConfig.width} 1fr`,
+ }
+ : undefined;
+
+ return (
+ <XDSMetadataListContext.Provider value={contextValue}>
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('metadata-list', {
+ columns: String(columns),
+ orientation,
+ }),
+ stylex.props(styles.root, xstyle),
+ className,
+ style,
+ )}>
+ {titleContent}
+ <dl
+ id={contentId}
+ style={dynamicGridStyle}
+ {...stylex.props(styles.dl, getGridStyle())}>
+ {visibleChildren}
+ </dl>
+ {isExceedMax && (
+ <button
+ type="button"
+ aria-controls={contentId}
+ aria-expanded={isShowAll}
+ onClick={() => setIsShowAll(prev => !prev)}
+ {...stylex.props(styles.toggleButton)}>
+ {isShowAll ? 'Show less' : 'Show more'}
+ </button>
+ )}
+ </div>
+ </XDSMetadataListContext.Provider>
+ );
+}
+
+XDSMetadataList.displayName = 'XDSMetadataList';
diff --git a/packages/core/src/MetadataList/XDSMetadataListContext.tsx b/packages/core/src/MetadataList/XDSMetadataListContext.tsx
new file mode 100644
index 0000000000..6ba6215123
--- /dev/null
+++ b/packages/core/src/MetadataList/XDSMetadataListContext.tsx
@@ -0,0 +1,23 @@
+'use client';
+
+/**
+ * @file XDSMetadataListContext.tsx
+ * @input Uses React createContext
+ * @output Exports XDSMetadataListContext for sharing config between XDSMetadataList and XDSMetadataListItem
+ * @position Internal context; consumed by XDSMetadataList.tsx and XDSMetadataListItem.tsx
+ */
+
+import {createContext} from 'react';
+
+export interface XDSMetadataListLabelConfig {
+ position: 'start' | 'top';
+ width?: number | string;
+}
+
+export interface XDSMetadataListContextValue {
+ labelConfig: XDSMetadataListLabelConfig;
+ orientation: 'vertical' | 'horizontal';
+}
+
+export const XDSMetadataListContext =
+ createContext<XDSMetadataListContextValue | null>(null);
diff --git a/packages/core/src/MetadataList/XDSMetadataListItem.tsx b/packages/core/src/MetadataList/XDSMetadataListItem.tsx
new file mode 100644
index 0000000000..d4d0fad079
--- /dev/null
+++ b/packages/core/src/MetadataList/XDSMetadataListItem.tsx
@@ -0,0 +1,211 @@
+'use client';
+
+/**
+ * @file XDSMetadataListItem.tsx
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, XDSMetadataListContext
+ * @output Exports XDSMetadataListItem component, XDSMetadataListItemProps type
+ * @position Core implementation; consumed by XDSMetadataList, index.ts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/MetadataList/MetadataList.doc.mjs
+ * - /packages/core/src/MetadataList/XDSMetadataList.test.tsx
+ * - /packages/core/src/MetadataList/index.ts
+ * - /apps/storybook/stories/MetadataList.stories.tsx
+ */
+
+import {useContext, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ typeScaleVars,
+ fontWeightVars,
+} from '../theme/tokens.stylex';
+import {XDSMetadataListContext} from './XDSMetadataListContext';
+import {xdsClassName, mergeProps} from '../utils';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSMetadataListItemProps {
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+ /**
+ * Content value for this metadata item.
+ */
+ children: ReactNode;
+ /**
+ * Icon rendered before the label text.
+ */
+ icon?: ReactNode;
+ /**
+ * Label text for this metadata item.
+ */
+ label: string;
+ /**
+ * StyleX styles created via `stylex.create()`.
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element.
+ */
+ style?: React.CSSProperties;
+ /**
+ * Test ID for testing frameworks.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ // Label (dt) — inline (side-by-side with value)
+ label: {
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ margin: 0,
+ padding: 0,
+ minHeight: 24,
+ wordBreak: 'break-word',
+ },
+ // Value (dd) — inline
+ value: {
+ color: colorVars['--color-text-primary'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ margin: 0,
+ padding: 0,
+ minHeight: 24,
+ wordBreak: 'break-word',
+ },
+ // Stacked layout wrapper (label on top)
+ stackedWrapper: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0-5'],
+ },
+ // Stacked label
+ stackedLabel: {
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ margin: 0,
+ padding: 0,
+ },
+ stackedValue: {
+ color: colorVars['--color-text-primary'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ margin: 0,
+ padding: 0,
+ wordBreak: 'break-word',
+ },
+ iconWrapper: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ flexShrink: 0,
+ color: colorVars['--color-text-secondary'],
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A single labeled metadata value within an XDSMetadataList.
+ *
+ * Renders a `<dt>` / `<dd>` pair. Layout (side-by-side or stacked) is
+ * determined by the parent XDSMetadataList's label configuration.
+ *
+ * @example
+ * ```
+ * <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>
+ * <XDSMetadataListItem label="Created" icon={<CalendarIcon />}>
+ * January 1, 2023
+ * </XDSMetadataListItem>
+ * ```
+ */
+export function XDSMetadataListItem({
+ children,
+ icon,
+ label,
+ xstyle,
+ className,
+ style,
+ 'data-testid': testId,
+ ref,
+}: XDSMetadataListItemProps) {
+ const ctx = useContext(XDSMetadataListContext);
+ const labelPosition = ctx?.labelConfig.position ?? 'start';
+ const isStacked =
+ labelPosition === 'top' || ctx?.orientation === 'horizontal';
+
+ const labelContent = (
+ <>
+ {icon != null && (
+ <span {...stylex.props(styles.iconWrapper)}>{icon}</span>
+ )}
+ {label}
+ </>
+ );
+
+ // Stacked layout: label above content, wrapped in a div
+ if (isStacked) {
+ return (
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('metadata-list-item'),
+ stylex.props(styles.stackedWrapper, xstyle),
+ className,
+ style,
+ )}>
+ <dt {...stylex.props(styles.stackedLabel)}>{labelContent}</dt>
+ <dd {...stylex.props(styles.stackedValue)}>{children}</dd>
+ </div>
+ );
+ }
+
+ // Inline layout: dt and dd are direct grid children
+ return (
+ <>
+ <dt
+ ref={ref}
+ data-testid={testId ? `${testId}-label` : undefined}
+ {...mergeProps(
+ xdsClassName('metadata-list-item'),
+ stylex.props(styles.label, xstyle),
+ className,
+ style,
+ )}>
+ {labelContent}
+ </dt>
+ <dd
+ data-testid={testId ? `${testId}-value` : undefined}
+ {...stylex.props(styles.value)}>
+ {children}
+ </dd>
+ </>
+ );
+}
+
+XDSMetadataListItem.displayName = 'XDSMetadataListItem';
diff --git a/packages/core/src/MetadataList/index.ts b/packages/core/src/MetadataList/index.ts
new file mode 100644
index 0000000000..b42041de07
--- /dev/null
+++ b/packages/core/src/MetadataList/index.ts
@@ -0,0 +1,18 @@
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from XDSMetadataList.tsx and XDSMetadataListItem.tsx
+ * @output Exports XDSMetadataList, XDSMetadataListItem components and their props/types
+ * @position Package entry point for MetadataList
+ *
+ * SYNC: When modified, update /packages/core/src/MetadataList/MetadataList.doc.mjs
+ */
+
+export {XDSMetadataList} from './XDSMetadataList';
+export type {
+ XDSMetadataListProps,
+ XDSMetadataListColumns,
+} from './XDSMetadataList';
+export {XDSMetadataListItem} from './XDSMetadataListItem';
+export type {XDSMetadataListItemProps} from './XDSMetadataListItem';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 42e3147803..82661370f8 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -29,6 +29,7 @@ export * from './Divider';
export * from './EmptyState';
export * from './Link';
export * from './List';
+export * from './MetadataList';
export * from './NavIcon';
export * from './NavItem';
export * from './Slider';