# Metadata List

## Usage

`MetadataList` lays out label and value pairs. `MetadataListItem` is one pair. A single column places the label beside the value. Several columns, or a numeric column count, stack the label above the value and repeat the track. `columns="multi"` uses `repeat(auto-fill, minmax(280px, 1fr))`.

`orientation="horizontal"` wraps the pairs in one row and ignores `columns`, `label`, and `maxNumOfItems`. `maxNumOfItems` hides the rest behind a show more control. `label.width` only applies when the label sits beside the value. A long label or value can break inside a word so a narrow container is not pushed wider. Extra attributes on `MetadataListItem` land on the `dt` when the label sits beside the value, and on the wrapper around the pair when the label is stacked above it.

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList>
    <MetadataListItem label="Name">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
  </MetadataList>
</template>
```

### Anatomy

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

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Keep labels short. The value is the thing a person came to read. |
| Do | Use one column for a narrow details pane, and `multi` when the pane is wide enough for several pairs. |
| Do | Set `maxNumOfItems` when a record has more fields than the page should show at once. |
| Don't | Put a long sentence in a label. The label track is sized for a short name. |
| Don't | Combine `orientation="horizontal"` with a column count and expect the count to apply. Horizontal layout ignores it. |

## Examples

### MetadataList — Basic

Single-column key-value metadata list.

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList>
    <MetadataListItem label="Name">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
  </MetadataList>
</template>
```

### MetadataList — Collapsible

Metadata list with a show-more toggle after a set number of items.

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList :max-num-of-items="3">
    <MetadataListItem label="Name">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
    <MetadataListItem label="Created">
      Jan 15, 2026
    </MetadataListItem>
    <MetadataListItem label="Updated">
      Mar 26, 2026
    </MetadataListItem>
    <MetadataListItem label="Priority">
      Tier 1
    </MetadataListItem>
  </MetadataList>
</template>
```

### MetadataList — Horizontal

Horizontal metadata items for compact inline display.

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList orientation="horizontal">
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Type">
      Premium
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
    <MetadataListItem label="Created">
      Jan 15, 2026
    </MetadataListItem>
  </MetadataList>
</template>
```

### MetadataList — Multi-Column

Multi-column metadata grid with token tags.

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
import { HStack } from '@astryx-vue/core/Stack'
import { Token } from '@astryx-vue/core/Token'
</script>

<template>
  <MetadataList columns="multi">
    <MetadataListItem label="Name">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
    <MetadataListItem label="Created">
      Jan 15, 2026
    </MetadataListItem>
    <MetadataListItem label="Tags">
      <HStack :gap="1">
        <Token label="component" />
        <Token label="xds" />
      </HStack>
    </MetadataListItem>
    <MetadataListItem label="Priority">
      Tier 1
    </MetadataListItem>
  </MetadataList>
</template>
```

## Props

### MetadataList

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `'multi' \| 'single' \| number` | `'single'` | One column keeps the label beside the value. A number or `multi` stacks the label above the value. `multi` fills tracks of at least 280px. |
| `label` | `{ position?: 'start' \| 'top', width?: number \| string }` | beside the value for one column, above it otherwise | `width` sizes the label track and only applies when the label sits beside the value. Numbers are pixels. |
| `maxNumOfItems` | `number` | - | Items past this count sit behind a show more control. Ignored when the list is horizontal. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Horizontal flow wraps pairs in a row and ignores `columns`, `label`, and `maxNumOfItems`. |
| `title` | `string` | - | Plain title above the pairs. Use the `title` slot for rich content. |

### MetadataListItem

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | - | The name of the field. The default slot is the value. The `icon` slot draws a leading icon. |

## Theming

`packages/core/styles/metadata-list.css` reads semantic tokens. Labels use the body size at medium weight and the secondary text color. Values use the primary text color. Side-by-side pairs have an 8px row gap and a 16px column gap, and the value row is at least 24px tall. Stacked pairs use a 2px gap. The title has 12px of space below it. The show more control uses the accent color.

## Native attributes

Attributes fall through to the root `<dl>` and to each item's `<dt>` or wrapping element.