List Component

Purpose

List Component is used to render a list of items using MUI List components. It provides a compact, single-column display ideal for navigation menus, contact lists, task lists, and other data that benefits from a linear presentation.

List Props

Property	Type	Default	Description
items	array | string	-	Data source - array, template string, or query reference
itemName	string	'item'	Variable name for each item in templates
itemProps	object	-	Item transformation properties
dividers	boolean	false	Show dividers between items
dense	boolean	false	Use compact spacing
disablePadding	boolean	false	Remove padding from list container
emptyMessage	string	-	Message to show when list is empty
containerSx	object	-	MUI sx props for list container
itemSx	object	-	MUI sx props for each list item
primaryField	string	-	Field name for primary text
secondaryField	string	-	Field name for secondary text
avatarField	string	-	Field name for avatar URL
enableSelect	string	-	Selection mode: 'Single' or 'Multiple'
onClick	object	-	Action to execute when item is clicked

Simple Example

component: list
name: contactsList
props:
  items:
    - name: John Smith
      email: [email protected]
      role: Developer
    - name: Jane Doe
      email: [email protected]
      role: Designer
    - name: Bob Wilson
      email: [email protected]
      role: Manager
  itemName: contact
  primaryField: name
  secondaryField: email
  dividers: true

Auto-Generated Template

When primaryField and secondaryField are specified, the list automatically generates content:

┌────────────────────────────────────────────────────┐
│ John Smith                                         │
│ [email protected]                                   │
├────────────────────────────────────────────────────┤
│ Jane Doe                                           │
│ [email protected]                                   │
└────────────────────────────────────────────────────┘

With Avatar

Display avatars for user/contact lists:

component: list
name: teamList
props:
  items: "{{ teamMembers }}"
  itemName: member
  primaryField: fullName
  secondaryField: role
  avatarField: avatarUrl
  dividers: true

When avatarField is specified:

• Avatar image is shown if URL is available
• First letter of primary text is shown as fallback

Selection

Single Selection

component: list
name: selectableList
props:
  items: "{{ options }}"
  itemName: option
  primaryField: label
  enableSelect: Single

Selected items are highlighted. Clicking a selected item deselects it.

Multiple Selection

component: list
name: multiSelectList
props:
  items: "{{ items }}"
  itemName: item
  primaryField: name
  enableSelect: Multiple

Checkboxes appear on the left side of each item.

Click Actions

Execute actions when items are clicked:

component: list
name: navigationList
props:
  items: "{{ menuItems }}"
  itemName: menuItem
  primaryField: label
  onClick:
    navigate: "{{ menuItem.path }}"

---

ListItem Component

Purpose

ListItem Component is an abstract component that wraps MUI List item components for web, enabling future React Native support. Use it inside a list or collection component for full control over item rendering, including built-in dropdown menu support.

ListItem Props

Property	Type	Default	Description
primaryComponent	object	-	Component for primary text area
secondaryComponent	object	-	Component for secondary text area
avatarComponent	object	-	Component for avatar/image area (left side)
selected	boolean	false	Show selected state
disabled	boolean	false	Disable interaction
divider	boolean	false	Show bottom divider
button	boolean	false	Make item clickable (renders as ListItemButton)
onClick	object	-	Action to execute on click
secondaryAction	object	-	Custom component for right side action
menu	object	-	Built-in icon menu configuration
sx	object	-	MUI sx styling

Menu Configuration

Property	Type	Default	Description
menu.icon	string	'ellipsis-vertical'	Icon for the menu trigger button
menu.items	array	-	Array of menu item configurations
menu.items[].label	string/object	-	Item label (supports localization)
menu.items[].icon	string	-	Optional icon for the item
menu.items[].onClick	object	-	Action to execute when clicked
menu.items[].disabled	boolean	false	Disable the menu item

ListItem Basic Example

component: listItem
props:
  primaryComponent:
    component: text
    props:
      value: "John Smith"
  secondaryComponent:
    component: text
    props:
      value: "[email protected]"
      color: textSecondary

ListItem with Avatar

component: listItem
props:
  avatarComponent:
    component: avatar
    props:
      src: "{{ contact.avatarUrl }}"
  primaryComponent:
    component: text
    props:
      value: "{{ contact.name }}"
  secondaryComponent:
    component: text
    props:
      value: "{{ contact.email }}"
      color: textSecondary

ListItem with Menu (Dropdown Actions)

component: listItem
props:
  primaryComponent:
    component: text
    props:
      value: "{{ contact.name }}"
  secondaryComponent:
    component: text
    props:
      value: "{{ contact.email }}"
  menu:
    icon: ellipsis-vertical
    items:
      - label: Edit
        icon: edit
        onClick:
          action: editContact
          contactId: "{{ contact.id }}"
      - label: Delete
        icon: trash
        onClick:
          action: deleteContact
          contactId: "{{ contact.id }}"

List with ListItem Children

For full control over list item rendering, use listItem as children of list:

component: list
name: contactsList
props:
  items: "{{ contacts }}"
  itemName: contact
  dividers: true
children:
  - component: listItem
    props:
      avatarComponent:
        component: avatar
        props:
          src: "{{ contact.avatarUrl }}"
      primaryComponent:
        component: text
        props:
          value: "{{ contact.name }}"
      secondaryComponent:
        component: text
        props:
          value: "{{ contact.email }}"
          color: textSecondary
      menu:
        items:
          - label: View Profile
            icon: user
            onClick:
              navigate: /contacts/{{ contact.id }}
          - label: Send Email
            icon: mail
            onClick:
              action: sendEmail
              email: "{{ contact.email }}"
          - label: Delete
            icon: trash
            onClick:
              action: deleteContact
              contactId: "{{ contact.id }}"
      button: true
      onClick:
        navigate: /contacts/{{ contact.id }}

Image Thumbnail Gallery

component: list
name: imageGallery
props:
  items: "{{ images }}"
  itemName: image
children:
  - component: listItem
    props:
      avatarComponent:
        component: image
        props:
          src: "{{ image.thumbnailUrl }}"
          width: 80
          height: 80
          sx:
            borderRadius: 1
      primaryComponent:
        component: text
        props:
          value: "{{ image.filename }}"
      secondaryComponent:
        component: text
        props:
          value: "{{ image.size }}"
          color: textSecondary
      button: true
      onClick:
        dialog:
          name: imageViewer
          props:
            imageUrl: "{{ image.fullUrl }}"

Custom Styled ListItem

component: listItem
props:
  primaryComponent:
    component: text
    props:
      variant: body1
      fontWeight: bold
      value: "{{ item.title }}"
  secondaryComponent:
    component: box
    props:
      sx:
        display: flex
        gap: 1
    children:
      - component: chip
        props:
          label: "{{ item.status }}"
          size: small
      - component: text
        props:
          variant: caption
          value: "{{ item.date }}"
  avatarComponent:
    component: avatar
    props:
      src: "{{ item.imageUrl }}"

ListItem with Custom Secondary Action

For advanced use cases, use secondaryAction with a custom component instead of the built-in menu:

component: listItem
props:
  primaryComponent:
    component: text
    props:
      value: "{{ task.title }}"
  secondaryAction:
    component: checkbox
    props:
      checked: "{{ task.completed }}"
      onChange:
        action: toggleTask
        taskId: "{{ task.id }}"

---

Additional List Features

Query Example (GraphQL)

Load items from a GraphQL query:

component: list
name: usersList
props:
  items:
    fromQuery:
      name: getUsers
      path: users.items
  itemName: user
  primaryField: fullName
  secondaryField: email
  avatarField: avatarUrl
  dividers: true
  dense: true
  queries:
    - name: getUsers
      query:
        command: >-
          query($organizationId: Int!, $take: Int!, $skip: Int!) {
            users(organizationId: $organizationId, take: $take, skip: $skip) {
              items {
                id
                fullName
                email
                avatarUrl
              }
              totalCount
            }
          }
        variables:
          organizationId: "{{ number organizationId }}"
          take: 50
          skip: 0

Styling

Container Styling

component: list
name: styledList
props:
  items: "{{ items }}"
  primaryField: name
  containerSx:
    maxHeight: 400
    overflow: auto
    border: 1px solid
    borderColor: divider
    borderRadius: 1

Item Styling

component: list
name: styledItems
props:
  items: "{{ items }}"
  primaryField: name
  itemSx:
    '&:hover':
      backgroundColor: action.hover
    borderLeft: 3px solid transparent
    '&.Mui-selected':
      borderLeftColor: primary.main

Dense Mode

For compact lists with many items:

component: list
name: compactList
props:
  items: "{{ notifications }}"
  itemName: notification
  primaryField: title
  secondaryField: timestamp
  dense: true
  disablePadding: true

Empty State

Display a message when the list is empty:

component: list
name: searchResults
props:
  items: "{{ searchResults }}"
  primaryField: title
  emptyMessage: "No results found. Try a different search term."

Accessing Item Index

To access the current item index, use {{ [itemName]Index }}:

component: list
name: numberedList
props:
  items: "{{ items }}"
  itemName: item
children:
  - component: text
    props:
      value: "{{ itemIndex + 1 }}. {{ item.name }}"

---

Comparison: List vs Collection

Feature	List	Collection
Layout	Single column	Responsive grid
Best for	Navigation, compact data	Cards, visual browsing
Selection UI	Checkboxes (Multiple), highlight (Single)	Checkboxes on cards
Avatar support	Built-in	Custom template required
Primary/Secondary text	Built-in	Custom template required
Dividers	Built-in	Not supported
Dense mode	Built-in	Not supported

When to Use List vs ListItem

Use Case	Component
Simple list with field mapping	list with primaryField/secondaryField
List with dropdown menus	list with listItem children + menu prop
Complex custom item layout	list with listItem children + component props
Standalone list item	listItem directly

Related Components

• Collection Component - Grid-based layout for cards
• DataGrid Component - Table with list view type support