Create custom Drupal forms with vertical tabs
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.
Further reading
- Drupal API Reference for class VerticalTabs
- Drupal Docs FieldTypes, FieldWidgets and FieldFormatters
- Drupal Docs Fieldsets
- Drupal Docs Form Render Elements
- Also see /core/lib/Drupal/Core/Render/Element/VerticalTabs.php in your project dir
.lowfidelity HEAVY INDUSTRIES is a Drupal development studio based in Vienna / Austria. lowfidelity offers development and maintenance for Drupal projects and offers a range of Drupal hosting solutions.