ListView Multiple Item Types

To display items with varied layouts in the same ListView, use a Conditional Builder as the child template. This allows you to create complex feeds, timelines, or mixed-content lists where each item can have a completely different structure.

Use Conditional Builder to render varied layouts per item type.

When to Use This Pattern

Use this approach when your list contains items of different types that need different visual representations:

• Social media feeds - Mix text posts, image posts, video posts, and ads

• E-commerce listings - Show products, category headers, and promotional banners

• Activity timelines - Display different event types (comments, likes, shares, etc.)

• Mixed content lists - Combine articles, videos, and interactive elements

How It Works

The key is to include a type identifier in your data source, then use a Conditional Builder to check that type and render the appropriate layout for each item.

Step-by-Step Implementation

1. Structure Your Data Source

Your data array should include a property that identifies the item type:

[
  {
    "type": "text",
    "content": "This is a simple text post",
    "author": "John Doe"
  },
  {
    "type": "image",
    "imageUrl": "https://example.com/photo.jpg",
    "caption": "Check out this photo!",
    "author": "Jane Smith"
  },
  {
    "type": "ad",
    "title": "Special Offer",
    "description": "Get 50% off today!",
    "ctaText": "Shop Now"
  }
]

The type field determines which layout to render for each item.

2. Add a Conditional Builder as the ListView Child

1. Select your ListView widget

2. Add a Conditional Builder as the single child

3. The Conditional Builder will be repeated for each item in the data source

3. Create Conditions Based on Item Type

In the Conditional Builder, add conditions that check the type property of currentItem:

Condition 1: ${isEqual(currentItem.type, 'text')}

• Build a simple text post layout (e.g., Column with Text widgets)

Condition 2: ${isEqual(currentItem.type, 'image')}

• Build an image post layout (e.g., Column with Image and caption)

Condition 3: ${isEqual(currentItem.type, 'ad')}

• Build an ad layout (e.g., Card with promotional content and button)

Default Case:

• Optionally add a fallback layout for unknown types

Example Layouts

Text Post Layout

Column
  ├─ Row (Author info)
  │   ├─ Avatar
  │   └─ Text (${currentItem.author})
  └─ Text (${currentItem.content})

Image Post Layout

Column
  ├─ Row (Author info)
  │   ├─ Avatar
  │   └─ Text (${currentItem.author})
  ├─ Image (${currentItem.imageUrl})
  └─ Text (${currentItem.caption})

Ad Layout

Card
  └─ Column
      ├─ Text (${currentItem.title})
      ├─ Text (${currentItem.description})
      └─ Button (${currentItem.ctaText})

Advanced Patterns

Using Switch-Case Logic

For more than 3-4 item types, consider using nested Conditional Builders or multiple conditions to keep your logic organized.

Accessing currentItem in Each Branch

Remember that ${currentItem} is available in all branches of the Conditional Builder. Each branch can access different properties based on the item type:

• Text posts: ${currentItem.content}, ${currentItem.author}

• Image posts: ${currentItem.imageUrl}, ${currentItem.caption}

• Ads: ${currentItem.title}, ${currentItem.ctaText}

Adding Item-Specific Actions

Each item type can have different event handlers:

• Text posts might open a detail page

• Image posts might open a full-screen viewer

• Ads might open an external URL

Use the onClick event handler on each layout and access ${currentItem} to pass the appropriate data to your action.

Best Practices

• Keep type identifiers consistent: Use clear, predictable type names like "text", "image", "video" rather than abbreviations

• Handle unknown types gracefully: Always include a default case in your Conditional Builder to handle unexpected item types

• Maintain consistent spacing: Even though layouts differ, keep consistent margins and padding for visual harmony

• Extract common elements: If multiple item types share common elements (like author info), consider creating reusable custom widgets

• Test with mixed data: Ensure your list looks good when different item types appear in various orders

Performance Considerations

• Conditional Builder is lightweight: It doesn't impact performance significantly, as only one branch is rendered per item

• Optimize heavy layouts: If some item types are particularly complex (e.g., video players), consider lazy loading or simplifying the layout

• Keep templates efficient: Even with varied layouts, maintain lightweight widget trees for smooth scrolling

Related Documentation

• Conditional Builder - Complete Conditional Builder widget reference

• ListView - Complete ListView widget reference

• Logical Operators - Learn about isEqual() and other comparison functions

• Custom Widgets - Create reusable components for complex item layouts