List Tips

The List field type repeats its child template for each item in an array. When designed well, Lists can display feature lists, team grids, product catalogs, and more.

Understanding List Behavior

How Lists Work

A List contains a child template (usually a Group) that defines what each item looks like. When the API provides an array, each element creates one instance of the template.

List (child template)              API Data
┌─────────────────────┐           [
│ ┌─────────────────┐ │             { icon: "...", title: "Fast" },
│ │ Icon │ Title    │ │    →        { icon: "...", title: "Secure" },
│ └─────────────────┘ │             { icon: "...", title: "Simple" }
└─────────────────────┘           ]

Result:
┌─────────────────────┐
│ 📦 │ Fast           │
├─────────────────────┤
│ 🔒 │ Secure         │
├─────────────────────┤
│ ✨ │ Simple         │
└─────────────────────┘

Direction Options

Direction	Behavior	Use Case
Vertical	Items stack top to bottom	Feature lists, bullet points
Horizontal	Items flow left to right	Icon bars, tag lists

Design Guidelines

Use Groups as Children

Always use a Group as the List's direct child. This gives you:

Grid layout for each item
Multiple fields per item
Consistent alignment

Good:
List
└── Group (child template)
    ├── Image
    └── Text

Avoid:
List
└── Text (single field - limited flexibility)

Consider Direction-Based Fill Rules

Fill sizing works differently based on List direction:

Direction	Width Fill	Height Fill
Vertical	Allowed	Not allowed
Horizontal	Not allowed	Allowed

This is because:

In a vertical list, all items share the same width, so children can fill that width
In a horizontal list, item widths vary, so you can't fill width; but height is shared

Set Appropriate Child Sizes

For vertical lists:

Child Group:
- Width: Fill (matches list width)
- Height: Hug (fits item content)

For horizontal lists:

Child Group:
- Width: Fixed or Hug (each item's width)
- Height: Fill (matches list height)

Mind the Item Count

Unlike Groups, List layouts depend on runtime data. Design for:

Minimum items: What if there's only 1 item?
Maximum items: What if there are 10 items?
Empty state: What if the array is empty?

Common Patterns

Pattern 1: Feature List

┌─────────────────────────────────────┐
│ List (vertical)                     │
│ ┌─────────────────────────────────┐ │
│ │ ⚡  │ Lightning fast performance │ │
│ ├─────────────────────────────────┤ │
│ │ 🔒 │ Bank-level security        │ │
│ ├─────────────────────────────────┤ │
│ │ 🎨 │ Beautiful design           │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

Configuration:
- Direction: Vertical
- Gap: 12px
- Child Group: 2 columns (icon + text)
  - Column 1: Hug content
  - Column 2: Fill container

Pattern 2: Team Grid

┌─────────────────────────────────────────────┐
│ List (horizontal)                           │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐   │
│ │   Photo   │ │   Photo   │ │   Photo   │   │
│ │   Name    │ │   Name    │ │   Name    │   │
│ │   Role    │ │   Role    │ │   Role    │   │
│ └───────────┘ └───────────┘ └───────────┘   │
└─────────────────────────────────────────────┘

Configuration:
- Direction: Horizontal
- Gap: 24px
- Child Group: 1 column, 3 rows
  - Width: Fixed (150px)
  - Height: Fill

┌─────────────────────────────────────┐
│ React  TypeScript  Node.js  Docker  │
└─────────────────────────────────────┘

Configuration:
- Direction: Horizontal
- Gap: 8px
- Child: Text with background styling
  - Width: Hug
  - Height: Hug

Pattern 4: Bullet Points

┌─────────────────────────────────────┐
│ • First key point                   │
│ • Second important item             │
│ • Third benefit                     │
└─────────────────────────────────────┘

Configuration:
- Direction: Vertical
- Gap: 8px
- Child Group: 2 columns
  - Column 1: Fixed (20px) for bullet
  - Column 2: Fill container for text

Pattern 5: Comparison Table

Use a Group + List combination for tables with a fixed header and dynamic rows:

┌─────────────────────────────────────────────────────┐
│ Group (2 rows: header + content list)               │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Group (Header Row)                              │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Features        │    Basic   │     Pro      │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ List (Content Rows) - vertical                  │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Monthly Exports │     100    │   Unlimited  │ │ │
│ │ ├─────────────────────────────────────────────┤ │ │
│ │ │ Team Seats      │       3    │   Unlimited  │ │ │
│ │ ├─────────────────────────────────────────────┤ │ │
│ │ │ Support         │       -    │      24/7    │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

Structure:
Group (tableContainer)
├── Group (headerRow) - Static column headers
│   ├── Text (headerFeatures): "Features"
│   ├── Text (plan1Name): dynamic
│   └── Text (plan2Name): dynamic
└── List (contentRows) - Dynamic rows
    └── Group (row) - Child template
        ├── Text (featureName)
        ├── Text (plan1Value)
        └── Text (plan2Value)

Configuration:
- Outer Group: 1 column, 2 rows
  - Row 1: Fixed (header height)
  - Row 2: Hug (fits content list)
- Header Group: N columns (one per data column)
  - All columns: Fixed width for alignment
- Content List: Vertical, Gap 2px
- Row Group: Same column widths as header

API Data:

{
  "tableContainer": {
    "headerRow": {
      "plan1Name": "Starter",
      "plan2Name": "Enterprise"
    },
    "contentRows": [
      {
        "row": {
          "featureName": "Monthly Exports",
          "plan1Value": "100",
          "plan2Value": "Unlimited"
        }
      },
      {
        "row": {
          "featureName": "Team Seats",
          "plan1Value": "3",
          "plan2Value": "Unlimited"
        }
      }
    ]
  }
}

Key Points:

Header and row Groups share the same column widths for alignment
List items wrap in a row object (child template key)
Use consistent column sizing between header and content rows

API Integration

Data Structure

List expects an array of objects:

{
  "content": {
    "feature_list": [
      {
        "feature_icon": "https://...",
        "feature_title": "Fast",
        "feature_description": "Lightning speed"
      },
      {
        "feature_icon": "https://...",
        "feature_title": "Secure",
        "feature_description": "Bank-level encryption"
      }
    ]
  }
}

Naming Conventions

Use consistent prefixes for fields within the same List item:

Good:
feature_icon, feature_title, feature_description

Bad:
icon, title, desc (too generic, may conflict with other fields)

Required Fields in Lists

When marking fields as required inside a List child:

Each item in the array must provide the required field
Empty arrays are allowed (unless the List itself is required)

Troubleshooting

"Items are overlapping"

Cause: Child elements have conflicting sizes or the Gap is 0.

Fix: Ensure children have proper Hug/Fixed sizing and add appropriate Gap.

"All items are the same size"

Cause: Child width/height is set to Fixed.

Fix: Use Hug for the dimension that should vary.

"List is empty but takes space"

Cause: The List has padding even with no items.

Fix: Consider conditionally hiding the List container when empty (handled in your API logic).

"Items wrap to next row unexpectedly"

Cause: Horizontal list items exceed container width.

Fix: Either use fewer items, smaller item widths, or adjust the List container width.

Best Practices Summary

Use Groups as children - Provides flexibility for complex items
Match sizing to direction - Fill width in vertical lists, fill height in horizontal
Plan for variable counts - Design works with 1 item or 10
Use consistent naming - Prefix all fields in a List item
Test with real data - Different text lengths, image sizes
Set appropriate gaps - Visual breathing room between items

List Tips

On this page