# useDocyrusAdaptiveCardItemList
URL: /docs/native/hooks/use-docyrus-adaptive-card-item-list

Generate an array of Adaptive Card JSON payloads from a Docyrus field list + many records, and render them as a responsive grid, a stacked list, a single Carousel card or a single Table card with the shared native AdaptiveCard renderer.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-adaptive-card-item-list
```

**Dependencies:**
- [react](https://react.dev)

The signature is identical to web `@docyrus/ui`. Only the rendered `view` differs: it is built from React Native `View`s.

## Overview

`useDocyrusAdaptiveCardItemList` is the list companion of
[`useDocyrusAdaptiveCardItemDetail`](/docs/native/hooks/use-docyrus-adaptive-card-item-detail).
You hand it a **Docyrus field list + a list of records** and it **generates one
Adaptive Card JSON payload per record** (`cards`) — mapping Docyrus field types
onto the Adaptive Cards element vocabulary — then renders them with the shared
[rn-adaptive-card](/docs/native/docyrus/adaptive-card) renderer.

Both hooks share the same backend-agnostic mapper, so a card looks identical
whether it's shown alone (detail) or in a list. Four layouts are supported:

- **`grid`** (default) — rows of equal-width cards. With `columns: 'flex'` the column count is derived from the **window width** (`useWindowDimensions`): `floor((width + gap) / (minCardWidth + gap))`, at least 1. A phone therefore gets one column and a tablet gets two or more. A fixed number pins the count.
- **`list`** — a single stacked column of cards.
- **`carousel`** — one combined Adaptive Card whose `Carousel` pages are the per-record bodies.
- **`table`** — one combined Adaptive Card whose `Table` has a field-label header row and one row per record (scalar fields become columns; images / rich-text / code are excluded). The native `Table` element gives every column a fixed width (`3` × 50 = 150 px) and scrolls horizontally inside a `ScrollView` when the columns are wider than the card.

When a [`DocyrusTenantProvider`](/docs/native/hooks/use-docyrus-tenant) is mounted,
dates / numbers / currency are formatted with the tenant's preferences.

See [`useDocyrusAdaptiveCardItemDetail`](/docs/native/hooks/use-docyrus-adaptive-card-item-detail#field-type--adaptive-card-element-mapping)
for the full field-type → element mapping and slot-detection rules.

## Usage

### Render a responsive grid of cards

```tsx
import { ScrollView } from 'react-native';

import { useDocyrusAdaptiveCardItemList } from '@/hooks/docyrus-native/use-docyrus-adaptive-card-item-list';

export function DealGallery({ fields, records }) {
  const { view } = useDocyrusAdaptiveCardItemList({
    fields,
    records,
    layout: 'grid',
    columns: 'flex',
    minCardWidth: 340
  });

  return ;
}
```

The `view` is a plain, non-virtualized `View` tree, so it can sit inside a `ScrollView`. For hundreds of records, render `items` yourself in a `FlashList` (`numColumns`) with one `` per cell.

### Per-card actions + scoped click handler

`onItemAction` receives the originating record and index, so one handler routes
every card (not applied in `carousel` or `table` layout).

```tsx
const { view } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  getItemActions: (record) => [
    { type: 'Action.OpenUrl', title: 'Open', url: `myapp://deals/${record.id}` }
  ],
  onItemAction: (event, record) => {
    if (event.type === 'openUrl') router.push(event.url);
  }
});
```

### Use the generated JSON array directly

```tsx
const { cards, items } = useDocyrusAdaptiveCardItemList({ fields, records });

// `cards` is AdaptiveCardPayload[] — one per record
// `items` is [{ id, record, card }] if you need the record alongside its card
await syncToTeams(cards);
```

### Carousel

```tsx
const { view, carouselCard } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  layout: 'carousel'
});

// `carouselCard` is the single combined AdaptiveCardPayload (a Carousel).
return view;
```

### Table

```tsx
const { view, tableCard } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  layout: 'table'
});

// `tableCard` is the single combined AdaptiveCardPayload (a Table:
// header row = field labels, one row per record). Scrolls horizontally
// when wider than its container.
return view;
```

## API Reference

### `UseDocyrusAdaptiveCardItemListOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `fields` | `DocyrusAdaptiveCardField[]` | — | Field metadata (accepts `IField` / `DataSourceField` / `DocyrusFieldLike`). |
| `records` | `Record<string, unknown>[] \| null` | — | Records to render as cards. |
| `enumOptions` | `Record<string, EnumOption[]>` | — | Per-field-slug enum options. Falls back to each field's inline `enums`. |
| `slots` | `DocyrusAdaptiveCardSlotOverrides` | — | Slot bindings shared by every card. |
| `includeFields` | `string[]` | — | Explicit, ordered body field list. |
| `excludeFields` | `string[]` | — | Field slugs to drop from every card body. |
| `hideEmpty` | `boolean` | `true` | Drop empty fields instead of rendering an em-dash. |
| `factLayout` | `'facts' \| 'stacked'` | `'facts'` | Scalar layout — a `FactSet` or stacked label/value blocks. |
| `version` | `string` | `'1.5'` | Adaptive Card schema version. |
| `getRecordId` | `(record, index) => string` | `record.id` → index | Stable key per record. |
| `getItemTitle` | `(record, index) => string \| undefined` | — | Per-card title override. |
| `getItemActions` | `(record, index) => AdaptiveCardAction[] \| undefined` | — | Per-card actions. |
| `onItemAction` | `(event: AdaptiveCardActionEvent, record, index) => void \| Promise<void>` | — | Action handler scoped to the record. Not applied in `carousel` / `table`. |
| `layout` | `'grid' \| 'list' \| 'carousel' \| 'table'` | `'grid'` | Rendered layout. `carousel` / `table` produce one combined card. |
| `columns` | `number \| 'flex'` | `'flex'` | Grid columns. `'flex'` derives the count from the window width and `minCardWidth`. |
| `minCardWidth` | `number` | `320` | Minimum card width (px) for the `'flex'` grid. |
| `gap` | `number` | `16` | Gap (px) between cards. |
| `className` | `string` | — | `className` for the list container `View` (or the combined carousel / table card). |
| `cardClassName` | `string` | — | `className` for each card (`grid` / `list`). |
| `emptyContent` | `ReactNode` | built-in | Shown when there are no records. The built-in state reads `ui.adaptiveCard.noRecords` (fallback "No records to display.") through `useUiTranslation`. |
| `formatDate` | `(value: unknown) => string` | tenant context | Override the date formatter. |
| `formatDateTime` | `(value: unknown) => string` | tenant context | Override the datetime formatter. |
| `formatNumber` | `DocyrusAdaptiveCardFormatters['formatNumber']` | tenant context | Override the number / currency / percent formatter. |
| `hostConfig` | `AdaptiveCardHostConfigOverride` | — | Forwarded to every rendered card. |
| `customElements` | `Record<string, ElementRenderer>` | — | Forwarded to every rendered card. |

### `UseDocyrusAdaptiveCardItemListReturn`

| Field | Type | Description |
|-------|------|-------------|
| `cards` | `AdaptiveCardPayload[]` | The generated Adaptive Card JSON payloads — the primary output. |
| `items` | `DocyrusAdaptiveCardListItem[]` | `{ id, record, card }` per record. |
| `slots` | `DocyrusAdaptiveCardSlots` | Slot bindings shared by every card. |
| `carouselCard` | `AdaptiveCardPayload \| null` | Combined `Carousel` card in `carousel` layout, else `null`. |
| `tableCard` | `AdaptiveCardPayload \| null` | Combined `Table` card in `table` layout (header row = field labels, one row per record), else `null`. |
| `view` | `ReactNode` | Ready-to-render list element. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusAdaptiveCardItemListOptions` | Hook options. |
| `UseDocyrusAdaptiveCardItemListReturn` | Hook return. |
| `DocyrusAdaptiveCardListItem` | `{ id, record, card }`. |
| `DocyrusAdaptiveCardListLayout` | `'grid' \| 'list' \| 'carousel' \| 'table'`. |
| `DocyrusAdaptiveCardField` | Minimal field shape. |
| `DocyrusAdaptiveCardSlots` / `DocyrusAdaptiveCardSlotOverrides` | Slot bindings / overrides. |
| `DocyrusAdaptiveCardFactLayout` | `'facts' \| 'stacked'`. |

## See also

- [`useDocyrusAdaptiveCardItemDetail`](/docs/native/hooks/use-docyrus-adaptive-card-item-detail) — single-record detail card + the full mapping table.
- [rn-adaptive-card](/docs/native/docyrus/adaptive-card) — the renderer.