Repeatable Field Group Configuration (Full Example)

The following example demonstrates a complete implementation of a repeatable field group using the Custom Paragraphs module inside a Drupal form. Each option is carefully configured to control behavior, validation, UI, and data handling.

$section['cards_wrapper'] = [
  '#type' => 'container', // Drupal container to group elements
  '#tree' => true, // Keeps form values structured in array format
  '#attributes' => [
    'id' => 'cards-wrapper', // Unique wrapper ID
  ],
];

$section['cards_wrapper']['cards'] = [
  '#type' => 'container', // Container for repeatable items
  '#attributes' => [
    'class' => ['cards-list'], // CSS class for styling & JS targeting

    // Main configuration passed to JavaScript
    'data-repeatable-field-group' => json_encode([

      // Label used for each item (e.g., Card 1, Card 2)
      'groupLabel' => 'Card',

      // Maximum number of items allowed
      'maxItems' => 8,

      // Minimum number of items required
      'minItems' => 1,

      // Number of items shown initially
      'initialItems' => 1,

      // Text for "Add" button
      'addButtonText' => 'Add another',

      // Text for "Remove" button
      'removeButtonText' => 'Remove',

      // CSS selector for hidden field where JSON is stored
      'hiddenInputSelector' => '.cards-list-hidden',

      // Prefix used for validation message classes
      'validationPrefix' => 'cards-list',

      // Prevent adding new item until current fields are valid
      'validateBeforeAdd' => true,

      // Custom ID for add button
      'addButtonId' => 'cards-list-add-button',

      // CSS classes for add button
      'addButtonClass' => ['btn', 'btn-primary', 'cards-list-add'],

      // Custom ID for remove button
      'removeButtonId' => 'cards-list-remove-button',

      // CSS classes for remove button
      'removeButtonClass' => ['btn', 'btn-danger', 'cards-list-remove'],

      // Store values as JSON (default true)
      'storeAsJson' => true,

      // Default values (useful for edit forms)
      'fieldGroupDefaultValue' => [],

      // Fields definition
      'fields' => [

        [
          'type' => 'text', // Input type
          'name' => 'title', // Field key in JSON
          'label' => 'Title', // Label shown in UI
          'placeholder' => 'Enter title', // Placeholder text
          'required' => true, // Mandatory field
          'requiredMessage' => 'Title is required.', // Error message
        ],

        [
          'type' => 'textarea', // Multi-line input
          'name' => 'description',
          'label' => 'Description',
          'placeholder' => 'Enter description',
          'required' => true,
          'requiredMessage' => 'Description is required.',

          // Enable CKEditor 5
          'editor' => 'ckeditor5',

          // Text format to use
          'editorFormat' => 'basic_html',
        ],

        [
          'type' => 'file', // File upload field
          'name' => 'icon',
          'label' => 'Icon',

          // Allow only single file
          'multiple' => false,

          // Allowed file types
          'accept' => 'png,jpg,jpeg,webp,svg,gif',

          'required' => true,
          'requiredMessage' => 'Icon is required.',

          // Drupal file system path
          'upload_location' => 'public://background-images/',
        ],

        [
          'type' => 'text',
          'name' => 'icon_alt_text',
          'label' => 'Icon alt text',
          'placeholder' => 'Enter icon alt text',
          'required' => true,
          'requiredMessage' => 'Icon alt text is required.',
        ],

        [
          'type' => 'file',
          'name' => 'image',
          'label' => 'Image',
          'multiple' => false,
          'accept' => 'png,jpg,jpeg,webp,svg,gif',
          'required' => true,
          'requiredMessage' => 'Image is required.',
          'upload_location' => 'public://background-images/',
        ],

        [
          'type' => 'text',
          'name' => 'image_alt_text',
          'label' => 'Image alt text',
          'placeholder' => 'Enter image alt text',
          'required' => true,
          'requiredMessage' => 'Image alt text is required.',
        ],

        [
          'type' => 'textfield', // Alias of text (optional usage)
          'name' => 'badge_text',
          'label' => 'Badge text',
          'placeholder' => 'Enter badge text',
          'required' => false,
        ],
      ],
    ]),
  ],
];


// Hidden field to store JSON data
$section['cards_wrapper']['cards_json'] = [
  '#type' => 'hidden', // Hidden input field
  '#default_value' => '', // Default empty value
  '#attributes' => [
    'class' => ['cards-list-hidden'], // Must match hiddenInputSelector
  ],
];

💡 Tip: Ensure that the .cards-list-hidden selector matches the hiddenInputSelector value, otherwise data will not be stored correctly.