useDocyrusAdaptiveCardItemList

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.

Edit on GitHubEditllms.txt

iOSAndroidExpo Go

Installation

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

Required Packages(1 package)

pnpm add react

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

Overview

useDocyrusAdaptiveCardItemList is the list companion of useDocyrusAdaptiveCardItemDetail. 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 AdaptiveCard 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 is mounted, dates / numbers / currency are formatted with the tenant's preferences.

See useDocyrusAdaptiveCardItemDetail for the full field-type → element mapping and slot-detection rules.

Usage

Render a responsive grid of cards

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 <ScrollView contentContainerClassName="p-4">{view}</ScrollView>;
}

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 <AdaptiveCard payload={item.card} /> 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).

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

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

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

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

Table

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