8.2.x theme.api.php hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state)
8.0.x theme.api.php hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state)
8.1.x theme.api.php hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state)
8.3.x theme.api.php hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state)
7.x theme.api.php hook_form_system_theme_settings_alter(&$form, &$form_state)

Allow themes to alter the theme-specific settings form.

With this hook, themes can alter the theme-specific settings form in any way allowable by Drupal's Form API, such as adding form elements, changing default values and removing form elements. See the Form API documentation on api.drupal.org for detailed information.

Note that the base theme's form alterations will be run before any sub-theme alterations.


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

$form_state: A keyed array containing the current state of the form.

2 functions implement hook_form_system_theme_settings_alter()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

color_form_system_theme_settings_alter in modules/color/color.module
Implements hook_form_FORM_ID_alter().
garland_form_system_theme_settings_alter in themes/garland/theme-settings.php
Implements hook_form_FORM_ID_alter().


modules/system/theme.api.php, line 87


function hook_form_system_theme_settings_alter(&$form, &$form_state) {
  // Add a checkbox to toggle the breadcrumb trail.
  $form['toggle_breadcrumb'] = array(
    '#type' => 'checkbox',
    '#title' => t('Display the breadcrumb'),
    '#default_value' => theme_get_setting('toggle_breadcrumb'),
    '#description' => t('Show a trail of links from the homepage to the current page.'),


hook_awesome’s picture

Does this hook have to be placed in the theme-settings.php file to work within a theme? It didn't execute when run from template.php within my subtheme.

darrell_ulm’s picture

Believe it does need to be in theme-settings.php