Same name and namespace in other branches

1. 7.x modules/system/system.api.php \hook_form_FORM_ID_alter()
2. 9 core/lib/Drupal/Core/Form/form.api.php \hook_form_FORM_ID_alter()
3. 8.9.x core/lib/Drupal/Core/Form/form.api.php \hook_form_FORM_ID_alter()
4. 10 core/lib/Drupal/Core/Form/form.api.php \hook_form_FORM_ID_alter()

Provide a form-specific alteration instead of the global hook_form_alter().

Implementations are responsible for adding cache contexts/tags/max-age as needed. See https://www.drupal.org/docs/8/api/cache-api/cache-api.

Modules can implement hook_form_FORM_ID_alter() to modify a specific form, rather than implementing hook_form_alter() and checking the form ID, or using long switch statements to alter multiple forms.

The call order is as follows: all existing form alter functions are called for module A, then all for module B, etc., followed by all for any base theme(s), and finally for the theme itself. The module order is determined by system weight, then by module name.

Within each module, form alter hooks are called in the following order: first, hook_form_alter(); second, hook_form_BASE_FORM_ID_alter(); third, hook_form_FORM_ID_alter(). So, for each module, the more general hooks are called first followed by the more specific.

Parameters

array $form: Nested array of form elements that comprise the form.

\Drupal\Core\Form\FormStateInterface $form_state: The current state of the form. The arguments that \Drupal::formBuilder()->getForm() was originally called with are available in the array $form_state->getBuildInfo()['args'].

string $form_id: String representing the name of the form itself. Typically this is the name of the function that generated the form.

See also

hook_form_alter()

hook_form_BASE_FORM_ID_alter()

\Drupal\Core\Form\FormBuilderInterface::prepareForm()

Related topics

42 functions implement hook_form_FORM_ID_alter()

Note: the procedural functions in this list are found by pattern matching, so the list may include some functions that are not actually implementations of this hook.

book_form_node_confirm_form_alter in core/modules/book/book.module

Implements hook_form_BASE_FORM_ID_alter() for \Drupal\node\Form\NodeDeleteForm.

book_form_node_form_alter in core/modules/book/book.module

Implements hook_form_BASE_FORM_ID_alter() for \Drupal\node\NodeForm.

ckeditor5_read_only_mode_form_node_page_form_alter in core/modules/ckeditor5/tests/modules/ckeditor5_read_only_mode/ckeditor5_read_only_mode.module

Implements hook_form_alter().

claro_form_media_form_alter in core/themes/claro/claro.theme

Implements hook_form_BASE_FORM_ID_alter() for \Drupal\media\MediaForm.

claro_form_media_library_add_form_alter in core/themes/claro/claro.theme

Implements hook_form_BASE_FORM_ID_alter().

... See full list

File

core/lib/Drupal/Core/Form/form.api.php, line 255

Code

function hook_form_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) : void {
  // Modification for the form with the given form ID goes here. For example, if
  // FORM_ID is "user_register_form" this code would run only on the user
  // registration form.
  // Add a checkbox to registration form about agreeing to terms of use.
  $form['terms_of_use'] = [
    '#type' => 'checkbox',
    '#title' => t("I agree with the website's terms and conditions."),
    '#required' => TRUE,
  ];
}

---