Kanban Layout

The kanban layout displays list data as cards organised into columns, where each column represents a value from an enum field. This view is ideal for workflow management, letting you visualise records at different stages of a process.

When to use kanban

Kanban works best when your data has a clear progression through defined stages. Common examples include:

• Order status - Track orders from placed to shipped to delivered
• Task management - Move tasks through todo, in progress, and done
• Approval workflows - Visualise items pending review, approved, or rejected
• Manufacturing stages - Monitor work orders through production phases

The key requirement is an enum field that represents the stages. Each enum value becomes a column, and records are grouped by their current value.

Configuration

To use the kanban layout, set the display layout type to BOARD and configure the boardConfig object:

{
  "id": "list-orders",
  "action_name": "listOrders",
  "display_layout": {
    "config": {
      "type": "BOARD",
      "boardConfig": {
        "groupByField": {
          "path": "$.status"
        },
        "title": {
          "template": "{{$.reference}}"
        },
        "description": {
          "template": "{{$.customer.name}}"
        },
        "getTool": {
          "toolId": "get-order"
        }
      }
    }
  }
}

Configuration options

Group by field

The groupByField determines which enum field creates the columns. Specify it using a JSON path:

{
  "groupByField": {
    "path": "$.status"
  }
}

The columns appear in the order the enum values are defined in your schema. For example, this enum:

enum OrderStatus {
  Placed
  Processing
  Shipped
  Delivered
}

Creates four columns from left to right: Placed, Processing, Shipped, Delivered.

Card display

Each record appears as a card within its column. Configure what appears on the card using templates:

{
  "title": {
    "template": "Order #{{$.reference}}"
  },
  "description": {
    "template": "{{$.customer.name}} - {{$.totalItems}} items"
  },
  "contextField": {
    "template": "{{$.totalAmount}}"
  }
}

Card avatars

Add visual identification to cards with avatars:

{
  "avatarEnabled": true,
  "avatarUrl": {
    "template": "{{$.customer.avatarUrl}}"
  },
  "avatarFallback": {
    "template": "{{$.customer.initials}}"
  }
}

When avatarEnabled is true, the card displays an image from avatarUrl. If the image fails to load, it shows the text from avatarFallback instead.

Clicking cards

Configure what happens when a user clicks a card by setting the getTool link:

{
  "getTool": {
    "toolId": "get-order"
  }
}

This navigates to the specified get tool, passing the record's ID automatically.

Moving cards between columns

To change a record's status, click the card to open the detail view, then use the update action to modify the enum field value. The kanban board refreshes automatically to show the card in its new column.

The updateAction configuration prepares the board for future drag-and-drop support:

{
  "updateAction": {
    "toolId": "update-order"
  }
}

Complete example

Here's a complete configuration for an order status kanban board:

enum OrderStatus {
  Placed
  Picking
  Packing
  Shipped
  Delivered
}
 
model Order {
  fields {
    reference Text @unique
    status OrderStatus @default(Placed)
    customer Customer
    totalAmount Decimal
    placedAt Timestamp @default(now())
  }
 
  actions {
    list listOrders(status?)
    get getOrder(id)
    update updateOrder(id) with (status?)
  }
}

{
  "id": "list-orders",
  "action_name": "listOrders",
  "name": "Order Board",
  "display_layout": {
    "config": {
      "type": "BOARD",
      "boardConfig": {
        "groupByField": {
          "path": "$.status"
        },
        "title": {
          "template": "{{$.reference}}"
        },
        "description": {
          "template": "{{$.customer.name}}"
        },
        "contextField": {
          "template": "£{{$.totalAmount}}"
        },
        "getTool": {
          "toolId": "get-order"
        },
        "updateAction": {
          "toolId": "update-order"
        }
      }
    }
  }
}

This creates a kanban board with five columns matching the OrderStatus enum values. Each order card shows its reference number, customer name, and total amount. Click a card to view full order details and update the status.

Column counts

Each column header displays a count of the records it contains. This gives a quick overview of how many items are at each stage of the workflow.

Empty states

When no records exist, the kanban board displays an empty state message. When records exist but a particular column is empty, that column still appears with a count of zero.

Pagination

The kanban layout supports pagination for large datasets. Pagination controls appear below the board, allowing users to navigate through pages of records. Each page loads records across all columns based on the current filter and sort settings.