List

Display records with shared fields or configure each item.

Use list(data) when every record has the same fields. Use list(data, callback) when individual rows need different fields or controls. Both forms accept the records first, so callbacks receive the record type.

Record list

import { defineResource, fields, list } from '@backlit/sdk'
const orders = defineResource('orders', [
  fields.text('title'),
  fields.number('total'),
])
const rows = [
  { title: 'Order A', total: 12 },
  { title: 'Order B', total: 25 },
]
orders.view('list', () =>
  list(rows).setFields({
    title: orders.get('title'),
    meta: orders.get('total'),
  })
)
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "list",
    "slots": {
      "content": [
        {
          "kind": "record-list",
          "fields": {
            "title": [
              {
                "kind": "text",
                "name": "title",
                "label": ""
              }
            ],
            "meta": [
              {
                "kind": "number",
                "name": "total",
                "label": ""
              }
            ]
          },
          "data": [
            {
              "title": "Order A",
              "total": 12
            },
            {
              "title": "Order B",
              "total": 25
            }
          ]
        }
      ]
    }
  }
}

setFields accepts leading, title, description, meta, and trailing. title requires at least one field. leading and trailing accept at most two fields each. meta accepts at most four. A position accepts one builder or an array of builders. Calling setFields replaces all positions.

onRowClick(linkTo(...)) makes a row a link. setRowActions accepts visit and action targets. Use setDensity('compact') to omit the description line. onDefect receives invalid field values with their row index.

Item list

import { defineResource, fields, list } from '@backlit/sdk'
const orders = defineResource('orders', [
  fields.text('title'),
  fields.number('total'),
])
const rows = [
  { title: 'Order A', total: 12 },
  { title: 'Order B', total: 25 },
]
orders.view('list', () =>
  list(rows, (item, row) => {
    item.setFields({
      title: orders.get('title'),
      meta:
        row.total > 20 ? orders.get('total') : undefined,
    })
  }).setDensity('compact')
)
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "list",
    "slots": {
      "content": [
        {
          "kind": "item-list",
          "density": "compact",
          "data": [
            {
              "title": [
                {
                  "field": {
                    "kind": "text",
                    "name": "title",
                    "label": ""
                  },
                  "value": "Order A"
                }
              ]
            },
            {
              "title": [
                {
                  "field": {
                    "kind": "text",
                    "name": "title",
                    "label": ""
                  },
                  "value": "Order B"
                }
              ],
              "meta": [
                {
                  "field": {
                    "kind": "number",
                    "name": "total",
                    "label": ""
                  },
                  "value": 25
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

The callback receives a fresh ListItemBuilder and the row. Call setFields, onClick, and setActions on that item. The same position limits apply. The item list itself supports setDensity, onDefect, and setPaginator. It does not have shared field declarations or a target registry.

Record lists support setPaginator and setSorter. See Search state. Passing an empty data array produces an empty list. A record list must still declare its title fields.