Understanding tree and parents in Drupal Form API

Understanding how Drupal structures submitted form data is essential when building complex or nested forms. In a technical blog post, Hari Venu explains how the #tree and #parents properties control how form values are stored and accessed.

Drupal flattens form values by default, meaning nested elements are stored as simple key-value pairs. Enabling #tree preserves the hierarchical structure of form elements, allowing grouped fields to retain their organisation when retrieved using $form_state->getValues(). The #parents property defines where a value is stored within the submitted data array, allowing developers to control its placement regardless of form structure.

The post demonstrates how these properties are applied in scenarios such as multi-value inputs, repeatable elements, and AJAX-driven forms, and notes that Drupal generates parent paths automatically unless overridden. Understanding these behaviours helps developers build more predictable and maintainable form systems.