Skip to main content

Field Collection Component

Purpose​

The field-collection component edits an array field inside a form. It renders one template per array item and supports add, remove, remove-all, drag-and-drop reorder, item defaults, list/grid/accordion item layouts, and grouped collections.

Use it for repeated sub-records such as line items, contacts, business hours, accessorial rows, or task lists.

Source update​

Frontend commit 8180273 added group-level grid controls for grouped collections:

  • groupCols controls how many groups render per row.
  • groupSpacing controls Material UI grid spacing between group columns.

These props only affect groupMode: true; item layout inside each group still uses layout, cols, and spacing.

Props​

  • fieldName (string, required): Form array field binding.
  • itemTemplate (component or component array, required): Template rendered for each item.
  • itemType (object | string | number | boolean | auto): Type of item to create and edit. Defaults to object.
  • options.allowAdd (boolean): Show add button. Defaults to true.
  • options.allowRemove (boolean): Show remove buttons. Defaults to true.
  • options.allowRemoveAll (boolean): Show remove-all button. Defaults to false.
  • options.allowReorder (boolean): Enable drag-and-drop reorder. Defaults to true.
  • options.minItems / options.maxItems (number): Minimum and maximum item counts.
  • addButton.label, addButton.icon, addButton.variant, addButton.position: Add button customization.
  • removeButton.label, removeButton.icon, removeButton.variant: Remove button customization.
  • defaultItem (any): Default values for newly added items.
  • layout (list | grid | accordion): Item layout mode. Defaults to list.
  • cols (number): Item grid columns when layout: grid.
  • spacing (number): Spacing between items.
  • groupMode (boolean): Enable grouping.
  • groupBy (string): Item field used as the group key.
  • groups (array): Group definitions with key, label, and optional icon.
  • groupTemplate (component): Optional custom group header template.
  • groupCols (number or breakpoint object): Number of group columns. Example: 2 or { xs: 1, md: 2, lg: 4 }. Defaults to 1.
  • groupSpacing (number): Spacing between group columns. Defaults to 0.
  • showIndex (boolean): Show item index numbers.
  • showDragHandle (boolean): Show drag handles.
  • showDivider (boolean): Show dividers between list items.
  • containerClass / itemClass (string): CSS class hooks.
  • itemTitle (string): Field name or template for accordion item title.
  • defaultExpanded (boolean): Expand accordion items by default.
  • label (localized string): Section label above the collection.

Grouped multi-column example​

component: field-collection
name: businessHours
props:
  fieldName: businessHours
  groupMode: true
  groupBy: dayOfWeek
  groupCols:
    xs: 1
    md: 2
    lg: 4
  groupSpacing: 2
  groups:
    - key: 1
      label: { en-US: Monday }
    - key: 2
      label: { en-US: Tuesday }
    - key: 3
      label: { en-US: Wednesday }
    - key: 4
      label: { en-US: Thursday }
    - key: 5
      label: { en-US: Friday }
    - key: 6
      label: { en-US: Saturday }
    - key: 0
      label: { en-US: Sunday }
  options:
    allowAdd: true
    allowRemove: true
    allowReorder: true
  defaultItem:
    startTime: "09:00:00"
    endTime: "17:00:00"
  layout: accordion
  itemTemplate:
    component: layout
    props:
      cols: 2
      spacing: 2
    children:
      - component: field
        name: startTime
        props:
          type: time
          label: { en-US: Start }
      - component: field
        name: endTime
        props:
          type: time
          label: { en-US: End }

Behavior notes​

  • In grouped mode, the component renders each configured group and filters items by groupBy.
  • Adding an item from a group automatically assigns that group's key to the groupBy field.
  • groupCols maps to a 12-column Material UI grid (groupCols: 3 renders each group at xs: 4).
  • Responsive groupCols values are converted per breakpoint, e.g. { md: 2 } becomes md: 6 grid width.