# MetadataList

- Page: https://jiguang132.com/resources/astryx/docs/metadata-list
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Metadata List

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.

| Prop | Type | Default | Description |
|---|---|---|---|
| children * | ReactNode |  | Metadata items (MetadataListItem components). |
| columns | 'multi' \| 'single' \| number | 'single' | Column layout mode. |
| label | { position?: 'start' \| 'top', width?: number \| string } | { 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' | '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. |

### Usage guidance

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

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-metadata-list",
      "visualProps": [
        "columns",
        "orientation"
      ]
    },
    {
      "className": "astryx-metadata-list-item"
    }
  ]
}
```

## MetadataListItem



### 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.

## Metadata List Item

A single labeled metadata value within an MetadataList.

| Prop | Type | Default | Description |
|---|---|---|---|
| children * | ReactNode |  | Content value for this metadata item. |
| label * | string |  | Label text for this metadata item. |
| icon | ReactNode |  | Icon rendered before the label text. |


## Examples

- Metadata List Item: Metadata list items displaying labeled values in various formats including text, badges, and links.
- Metadata List: 
- MetadataList — Basic: Single-column key-value metadata list.
- MetadataList — Collapsible: Metadata list with a show-more toggle after a set number of items.
- MetadataList — Horizontal: Horizontal metadata items for compact inline display.
- MetadataListItem — Basic: Labeled key-value rows inside a MetadataList. Values accept any content, from plain text to components like Badge.
- MetadataList — Multi-Column: Multi-column metadata grid with token tags.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt