---
title: Datalist
description: Display one record as a list of labeled values.
---

A datalist block displays one record through a declared set of fields. Use it for a
detail view or for a short record summary.

The fields control the order, labels, and display variants. The data supplies the
raw values. The SDK remaps each value to the protocol format before it sends the
node.

## API

```ts
datalist(data: Row): DatalistBuilder<Row>
```

| Method      | Input                      | Result                                              |
| ----------- | -------------------------- | --------------------------------------------------- |
| `setFields` | `Nodeable<Field>[]`        | Sets the fields and their order.                    |
| `peers`     | `...string[][]`            | Puts each field set on one shared row.              |
| `onDefect`  | `(defect: Defect) => void` | Handles values that the SDK cannot put on the wire. |

Calling `setFields` or `peers` again replaces the previous value.

## Basic datalist

Pass one raw record to `datalist(data)`, then set the fields. Only declared fields go into the
protocol output.

<BacklitExample path="datalist/basic" view="detail" />

## Datalist inside a panel

Put a datalist inside a panel when the record needs a title or a bounded
surface. The panel supplies the surrounding metadata. The datalist supplies the
labeled values.

<BacklitExample path="datalist/panel" view="detail" />

## Selected fields

Use `resource.pick` to select fields and set their display order. Extra keys in
the raw record do not go into the protocol output.

<BacklitExample path="datalist/selected_fields" view="detail" />

## Peer fields

Use `peers` when two or more values must share one row. Fields that are not in a
peer set stay on separate rows.

<BacklitExample path="datalist/peers" view="detail" />

### Multiple peer rows

Pass multiple field sets to create multiple peer rows.

<BacklitExample path="datalist/multiple_peer_rows" view="detail" />

## Grouped fields

A group combines multiple raw fields into one datalist value. The protocol puts
the child values under the group name.

<BacklitExample path="datalist/group" view="detail" />

## Default remapping

The default remapper converts common adapter values to the protocol format. For
example, it converts numeric strings to numbers, `0` or `1` to booleans, and
date inputs to ISO strings.

<BacklitExample path="datalist/remapping" view="detail" />

## Global remapper

Use `remappers.registerRemappers` when an adapter uses a different value format.
The change applies to the role in all blocks. A datalist does not accept local
remapper overrides.

<BacklitExample path="datalist/custom_remapper" view="detail" />

## Defect reporter

A defect occurs when a field is missing or its value cannot be remapped. The
SDK leaves that field out of the data and sends the defect to the reporter. If
you do not set a reporter, the SDK writes a warning to the console.

<BacklitExample path="datalist/defect_reporter" view="detail" />

## All options

You can use peer rows and a defect reporter on the same datalist.

<BacklitExample path="datalist/all_options" view="detail" />

## Field roles

`setRoles({ fieldName: role })` selects roles for individual fields and replaces
the previous selections. The default role is `display` in tables and datalists,
and `input` in form field blocks. See [Field roles](/advanced/field-roles).