List Views

List views display records in a table format.

Basic List

{
  "data_type": "UiView",
  "identifier": "contact_list_view",
  "type": "List",
  "model": "Contact",
  "arch": [
    {
      "content": [
        {"type": "field", "name": "name", "properties": {"widget": "Text"}},
        {"type": "field", "name": "email", "properties": {"widget": "Text"}},
        {"type": "field", "name": "phone", "properties": {"widget": "Text"}},
        {"type": "field", "name": "active", "properties": {"widget": "Badge"}}
      ]
    }
  ]
}

Column Configuration

Basic Column

{
  "type": "field",
  "name": "name",
  "properties": {
    "widget": "Text"
  }
}

Column with Options

{
  "type": "field",
  "name": "status",
  "properties": {
    "widget": "Badge",
    "colors": {
      "draft": "gray",
      "active": "green",
      "archived": "red"
    }
  }
}

Column Properties

List columns support visibility, readonly, required, and group-based access control. These work with both boolean values and Q-expressions for conditional behavior.

Property	Type	Description
visible	Boolean/String	Hide column or use Q-expression. Default: true
readonly	Boolean/String	Make cells read-only or use Q-expression
required	Boolean/String	Make cells required or use Q-expression
groups	Array	User must be in one of these groups to see the column
mobile	Boolean	Include field in mobile card view. Default: true

Hide Column

{
  "type": "field",
  "name": "internal_code",
  "properties": {
    "widget": "Text",
    "visible": false
  }
}

Group-Restricted Column

{
  "type": "field",
  "name": "cost_price",
  "properties": {
    "widget": "Text",
    "groups": ["inventory.manager", "admin"]
  }
}

Mobile-Only Fields

On tablet/mobile devices, List views are rendered as card layouts (Kanban-style). Use mobile: false to exclude columns that are useful in desktop tables but not needed on compact mobile cards:

{
  "type": "field",
  "name": "internal_notes",
  "properties": {
    "widget": "Text",
    "mobile": false
  }
}

This field will appear in the desktop table view but be hidden in the mobile card layout.

Conditional Readonly (per-row)

For inline editable lists, readonly can be evaluated against each row’s data:

{
  "type": "field",
  "name": "quantity",
  "properties": {
    "widget": "NumberInput",
    "readonly": "Q(status__neq='draft')"
  }
}

Conditional Required (per-row)

{
  "type": "field",
  "name": "shipping_address",
  "properties": {
    "widget": "DataCombo",
    "required": "Q(requires_shipping__eq=true)"
  }
}

Common List Widgets

Widget	Description
Text	Plain text display
Badge	Colored badge
Tags	Multiple tags
Avatar	User avatar
Image	Image thumbnail
Checkbox	Boolean checkbox
Rating	Star rating

Editable Lists

Enable inline editing with editable: true at the arch root level:

{
  "data_type": "UiView",
  "type": "List",
  "model": "OrderLine",
  "arch": [
    {
      "editable": true,
      "insertPosition": "bottom",
      "content": [
        {"type": "field", "name": "product", "properties": {"widget": "DataCombo"}},
        {"type": "field", "name": "quantity", "properties": {"widget": "NumberInput"}}
      ]
    }
  ]
}

Property	Description
editable	true to enable inline editing
insertPosition	Where new rows are added: "bottom" (default) or "top"

Badge Colors

{
  "type": "field",
  "name": "priority",
  "properties": {
    "widget": "Badge",
    "size": "sm",
    "colors": {
      "low": "gray",
      "medium": "blue",
      "high": "orange",
      "urgent": "red"
    }
  }
}

Related Fields

Display related model fields:

{
  "type": "field",
  "name": "customer",
  "properties": {
    "widget": "Text"
  }
}

The display name of the related record is shown.

Image Column

{
  "type": "field",
  "name": "image",
  "properties": {
    "widget": "Image",
    "h": 40,
    "w": 40,
    "fit": "cover"
  }
}

Complete Example

{
  "data_type": "UiView",
  "identifier": "product_list_view",
  "type": "List",
  "model": "Product",
  "arch": [
    {
      "content": [
        {
          "type": "field",
          "name": "image",
          "properties": {
            "widget": "Image",
            "h": 40,
            "w": 40,
            "fit": "contain"
          }
        },
        {
          "type": "field",
          "name": "name",
          "properties": {
            "widget": "Text",
            "fw": "600"
          }
        },
        {
          "type": "field",
          "name": "sku",
          "properties": {
            "widget": "Text",
            "c": "dimmed"
          }
        },
        {
          "type": "field",
          "name": "category",
          "properties": {
            "widget": "Text"
          }
        },
        {
          "type": "field",
          "name": "price",
          "properties": {
            "widget": "Text"
          }
        },
        {
          "type": "field",
          "name": "stock_quantity",
          "properties": {
            "widget": "Text"
          }
        },
        {
          "type": "field",
          "name": "active",
          "properties": {
            "widget": "Badge",
            "colors": {
              "true": "green",
              "false": "gray"
            }
          }
        }
      ]
    }
  ]
}

Drag-and-Drop Row Reordering

List views can enable drag-and-drop row reordering via the reorderable property. When enabled, a drag handle column appears and users can reorder rows by dragging.

Enabling Reordering

{
  "data_type": "UiView",
  "type": "List",
  "model": "CrmStage",
  "arch": [
    {
      "reorderable": "sequence",
      "content": [
        {"type": "field", "name": "sequence"},
        {"type": "field", "name": "name"},
        {"type": "field", "name": "probability"}
      ]
    }
  ]
}

Reorderable Property Values

Value	Description
false or omitted	Drag-and-drop disabled (default)
"sequence"	Enable reordering, update the sequence field
"priority"	Enable reordering, update the priority field
Any field name	Enable reordering, update that Integer field

Automatic Disabling

Drag-and-drop reordering is automatically disabled when:

• List is grouped (group-by is active)
• Column sorting is active (user clicked a column header to sort)
• Inline editing mode is active
• Action context has editable: false

Embedded List (in Forms)

Lists inside form views for related records:

{
  "type": "field",
  "name": "order_lines",
  "properties": {
    "widget": "List",
    "create": true,
    "delete": true,
    "editable": true,
    "view": "order_line_inline_view",
    "context": {
      "form_identifier": "order_line_form_view"
    }
  }
}

Embedded List Options

Option	Description
create	Allow adding new records
delete	Allow deleting records
editable	true for inline editing, "modal" for modal editing
insertPosition	Where new items are added: "bottom" (default) or "top"
view	List view to use
context	Additional context (form_identifier)

Embedded List Reordering

Embedded lists (OneToMany fields in forms) also support drag-and-drop reordering. Configure reorderable on the referenced list view:

{
  "data_type": "UiView",
  "identifier": "order_line_inline_view",
  "type": "List",
  "model": "OrderLine",
  "arch": [
    {
      "reorderable": "sequence",
      "content": [
        {"type": "field", "name": "sequence"},
        {"type": "field", "name": "product"},
        {"type": "field", "name": "quantity"}
      ]
    }
  ]
}

Then reference this view in your form:

{
  "type": "field",
  "name": "order_lines",
  "properties": {
    "widget": "List",
    "editable": true,
    "view": "order_line_inline_view"
  }
}

Key differences from main List views:

• Updates form state directly (no API call on drag)
• Sequence field is updated for all rows in form state
• Disabled while editing a row inline

Responsive Behavior (Mobile/Tablet)

On tablet and mobile devices (≤1024px), List views automatically render as a card layout (similar to Kanban) for better touch interaction and readability.

How It Works

1. Desktop: Displays as a traditional data table with columns
2. Tablet/Mobile: Displays as stacked cards, with each row becoming a card

Card Layout Conversion

When converting to cards:

• First visible column becomes the card title (bold, larger text)
• Remaining columns become secondary fields (smaller, some dimmed)
• Input widgets are converted to display widgets (e.g., TextInput → Text)
• Fields with mobile: false are excluded

Controlling Mobile Display

Use the mobile property to control which fields appear in the mobile card:

{
  "arch": [
    {
      "content": [
        {"type": "field", "name": "name", "properties": {"widget": "Text"}},
        {"type": "field", "name": "customer", "properties": {"widget": "Text"}},
        {"type": "field", "name": "total", "properties": {"widget": "Text"}},
        {"type": "field", "name": "internal_ref", "properties": {"widget": "Text", "mobile": false}},
        {"type": "field", "name": "notes", "properties": {"widget": "Text", "mobile": false}}
      ]
    }
  ]
}

In this example, name, customer, and total appear on mobile cards, while internal_ref and notes are desktop-only.

Custom Mobile Layout

For more control over mobile display, define a separate Kanban view. The system checks for a Kanban view before converting the List view:

{
  "data_type": "UiView",
  "identifier": "order_kanban_view",
  "type": "Kanban",
  "model": "Order",
  "arch": [
    {
      "type": "row",
      "content": [
        {
          "type": "column",
          "span": 12,
          "content": [
            {"type": "field", "name": "number", "properties": {"widget": "Text", "size": "sm", "fw": "600"}},
            {"type": "field", "name": "customer", "properties": {"widget": "Text", "size": "xs", "c": "dimmed"}},
            {"type": "field", "name": "total", "properties": {"widget": "Text", "size": "xs"}}
          ]
        }
      ]
    }
  ]
}

Next Steps

• Stats Banner - Rich visual stats above list views
• Kanban Views - Card-based views
• Widgets - All available widgets