Drupal

Drupal Form API: Vertical Tabs

How to programmatically create custom Drupal forms with vertical tabs.

Mehr erfahren

Create custom Drupal forms with vertical tabs

How to programmatically create custom Drupal forms with vertical tabs.

Autor

Paper Boy

Datum

04.November 2021

This example demonstrates how to create custom froms with a vertical tab bar using the Drupal Form API supplied by Drupal core.

While writing this guide there is only support for vertical tabs in Drupal core. Find out more about this feature's state and alternatives at #1168364 add horizontal tabs supports to FAPI. Horizontal tabs are provided by the Field Group module.

Steps involved

Create grouping elements (fieldset or details).
Place fields in the grouping elements.
Create a vertical tabs bar.
Place the grouping elements in the tabs bar.

Create grouping elements and insert form fields

Even though there exists a fieldset render element ('#type' => 'fieldset') the Drupal fieldsets documentation recommends using the details render element ('#type' => 'details') if „you are looking to visually organize a group of form elements“. As far as this example is concerned, both types of fields can be used equally.

public function buildForm(array $form, FormStateInterface $form_state) {
    // Create a grouping element using a fieldset.
    $form['demofieldset'] = [
      '#type' => 'fieldset',
      '#title' => $this->t('A fieldset'),
      // Show collapse icon.
      '#collapsible' => TRUE,
      // Open by default.
      '#collapsed' => FALSE,
    ];

    // Create a grouping element using a details element.
    $form['demofieldset2'] = [
      '#type' => 'details',
      '#title' => $this->t('A details element'),
      // Open by default.
      '#open' => TRUE,
    ];

    // Place a textfield in the first fieldset.
    $form['demofieldset']['field1'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Textfield 1'),
    ];

    // Place a textfield in the details element.
    $form['demofieldset2']['field2'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Textfield 2'),
    ];
}

Depending on your theme, the output (visually as well as the code) might be the same for both types of form fields.

Show the grouping elements as vertical tabs

Now the grouping elements created above can be displayed as tabs of a vertical tab bar. Create a Vertical Tabs element and assign it's ID to the grouping elements.

public function buildForm(array $form, FormStateInterface $form_state) {

    $form['verticaltabs'] = [
      '#type' => 'vertical_tabs',
      // Open the second tab by default.
      // Find the target element's ID by using your browser's debugger.
      //'#default_tab' => 'edit-demofieldset2',
    ];

    // Create a grouping element using a fieldset.
    $form['demofieldset'] = [
      '#type' => 'fieldset',
      '#title' => $this->t('A fieldset'),
      // Show collapse icon.
      '#collapsible' => TRUE,
      // Open by default.
      '#collapsed' => FALSE,
      // Place this group in the vertical tabs bar.
      '#group' => 'verticaltabs',
    ];

    // Create a grouping element using a details element.
    $form['demofieldset2'] = [
      '#type' => 'details',
      '#title' => $this->t('A details element'),
      // Open by default.
      '#open' => TRUE,
      // Place this group in the vertical tabs bar.
      '#group' => 'verticaltabs',
    ];

    // Place a textfield in the first fieldset.
    $form['demofieldset']['field1'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Textfield 1'),
    ];

    // Place a textfield in the details element.
    $form['demofieldset2']['field2'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Textfield 2'),
    ];
}

This will display a vertical tab bar with two tabs. The grouping elments' titles are used as tab labels.

Create custom Drupal forms with vertical tabs

Steps involved

Create grouping elements and insert form fields

Show the grouping elements as vertical tabs

Further reading