---
id: "packages/active-ui/property-list"
title: "PropertyList"
description: "A reference list of properties - name, labels, type and default beside their meaning - that stacks on narrow screens."
url: "/packages/active-ui/property-list"
locale: "en"
revision: "f11040cbec3bd098"
---

# PropertyList

`PropertyList` lists the props of a component, the fields of a type or the options of a function.
Per property the name and its meaning lead; labels, type and default support them. The API
sections of this site are built from it.

**Example: Two properties**

Client: Runs entirely in your browser. Source: `examples/ui/property-list.tsx`.

```tsx
// apps/docs/examples/ui/property-list.tsx
import {Code} from '@workspace/active-ui/components/composed/code';
import {
  DescriptionItem,
  DescriptionList,
} from '@workspace/active-ui/components/composed/description-list';
import {
  PropertyList,
  PropertyListItem,
} from '@workspace/active-ui/components/composed/property-list';
import {Badge} from '@workspace/active-ui/components/primitives/badge';

/**
 * A reference list of two properties, each with labels, its type and
 * default, and its meaning. With an `id` the name links to the property.
 * The API sections of this site are built from it.
 */
export default function PropertyListExample() {
  return (
    <PropertyList className="w-full max-w-2xl">
      <PropertyListItem
        id="example-value"
        name="value"
        badges={<Badge variant="outline">required</Badge>}
        meta={
          <DescriptionList orientation="inline" columns={1}>
            <DescriptionItem label="Type">
              <Code>string</Code>
            </DescriptionItem>
          </DescriptionList>
        }
      >
        The chosen calendar day as <Code>YYYY-MM-DD</Code>, or an empty string.
      </PropertyListItem>
      <PropertyListItem
        id="example-placeholder"
        name="placeholder"
        meta={
          <DescriptionList orientation="inline" columns={1}>
            <DescriptionItem label="Type">
              <Code>string</Code>
            </DescriptionItem>
            <DescriptionItem label="Default">
              <Code>the input pattern</Code>
            </DescriptionItem>
          </DescriptionList>
        }
      >
        Text in the empty field.
      </PropertyListItem>
    </PropertyList>
  );
}
```

## What the composition adds

- **Two layouts**: from the `md` width the name with its facts sits beside the description; below
  it everything stacks in one column, so nothing scrolls sideways.
- **Names that break well**: a long name breaks between its words, never inside one.
- **Links to one property**: with an `id` the name is a link to the property itself.
- **Slots for the rest**: `badges` beside the name, `meta` below it (usually a
  [DescriptionList](/packages/active-ui/description-list) with [Code](/packages/active-ui/code)), the
  description as children, and `extra` for, say, the full type folded out.
- **Details across both columns**: `details` sits below name and description over the full width
  of the item, for the fields of an object the property takes (a nested `PropertyList`) or a long
  signature. A nested list then keeps the width of its parent instead of losing the name column
  again at every level.

## Usage

```tsx
import {
  PropertyList,
  PropertyListItem,
} from '@workspace/active-ui/components/composed/property-list';

<PropertyList>
  <PropertyListItem id="dialog-open" name="open" meta={…}>
    Whether the dialog is open.
  </PropertyListItem>
</PropertyList>;
```

## What your application provides

The names, facts and descriptions, translated: the list knows no type system.

## API

**PropertyList**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

PropertyList has no props of its own.

**PropertyListItem**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `ReactNode` | yes | The property name, shown in the monospace stack. A name too long for its column breaks between its words (camelCase, `_`, `.`), never inside one. |
| `badges` | `ReactNode` | no | Labels beside the name, such as "required" or "deprecated". |
| `children` | `ReactNode` | no | What the property means. |
| `details` | `ReactNode` | no | Below name and description, across both columns: for example the fields of an object the property takes, as a nested `PropertyList`, or a long signature. |
| `extra` | `ReactNode` | no | Below the description: for example the full type, folded out. |
| `id` | `string` | no | The anchor of this property. With an `id` the name links to it, so a reader can share a link to one property. |
| `meta` | `ReactNode` | no | The supporting facts below the name: type, default, origin. |

**PropertyListItemProps**

```ts
interface PropertyListItemProps extends Omit<
  React.ComponentProps<'div'>,
  'children'
> {
  name: React.ReactNode;
  id?: string;
  badges?: React.ReactNode;
  meta?: React.ReactNode;
  children?: React.ReactNode;
  extra?: React.ReactNode;
  details?: React.ReactNode;
}
```