A Drupal fieldset example (Drupal form group)

By Alvin Alexander. Last updated: June 4, 2016

Drupal form fieldset FAQ: How do I build a Drupal form using one or more fieldset areas to group my form elements into logical components (like 'shipping address', 'billing address', 'credit card information', and so on)?

As inferred by the question, you group Drupal form elements using the Drupal fieldset element. You define a fieldset, then add form elements to that fieldset using a simple sub-array syntax. For example, in the following Drupal source code example I define a fieldset using an array like this:

$form['name'] = ...

Each Drupal form element that I then want to be in that fieldset is declared to be a sub-array of this main array. For instance, the textfield for the user's first name is declared like this:

$form['name']['firstname'] = ...

The top-level array $form['name'] defines our Drupal fieldset, and then the sub-array $form['name']['firstname'] defines the first name textfield, which is this first element in our fieldset.

Drupal form fieldset example source code

Here's the source code for a function that completely defines a Drupal fieldset and two elements in the Drupal fieldset where the user can enter their first and last names:

#
# a function that builds a drupal form
# with a fieldset
#
function my_module_my_form($form_state) {

  #--------------------------------------
  # define your drupal 'fieldset' element
  #--------------------------------------
  $form['name'] = array(
    '#type' => 'fieldset',
    '#title' => t('Name'),
  );

  #--------------------------------------------------------
  # create a form element as a sub-array of your
  # top-level fieldset element; notice that this element is
  # declared as "$form['name']['firstname']" -- a sub-array
  # of the fieldset element.
  #--------------------------------------------------------
  $form['name']['firstname'] = array(
    '#type' => 'textfield',
    '#title' => t('First name'),
  );
  
  #----------------------------------------
  # define another textfield as a sub-array
  # of your fieldset elements
  #----------------------------------------
  $form['name']['lastname'] = array(
    '#type' => 'textfield',
    '#title' => t('Last name'),
  );
 
  #------------------------
  # a typical submit button 
  #------------------------
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => 'Submit',
  );
  return $form;
}

(Note: This source code is partially based on this source code on the Drupal website.)

Here's what this Drupal fieldset example looks like in your browser:

A Drupal form fieldset example (form groups)

As you can see, a fieldset lets you organize your forms into logical Drupal form groups, which can make them easier for your users.

You can also add additional Drupal fieldset options to make your fieldset collapsible like this:

'#collapsible' => TRUE,

and initially collapsed like this:

'#collapsed' => TRUE,

Multiple Drupal form fieldsets

For a more complete Drupal fieldset example, here's a complete Drupal form builder function that demonstrates how to create two fieldsets on a Drupal form, a "Name" fieldset and an "Address" fieldset:

function firstmodule_form1($form_state) {

  #--------------------------------------
  # create a "name" fieldset
  #--------------------------------------
  $form['name'] = array(
    '#type' => 'fieldset',
    '#title' => t('Name'),
    '#collapsible' => TRUE,
  );

  $form['name']['firstname'] = array(
    '#type' => 'textfield',
    '#title' => t('First name'),
    '#value' => 'Fred',
  );
  
  $form['name']['lastname'] = array(
    '#type' => 'textfield',
    '#title' => t('Last name'),
  );
 
  #--------------------------------------
  # create an "address" fieldset
  #--------------------------------------
  $form['address'] = array(
    '#type' => 'fieldset',
    '#title' => t('Address'),
  );

  $form['address']['street'] = array(
    '#type' => 'textfield',
    '#title' => t('Street'),
  );
  
  $form['address']['city'] = array(
    '#type' => 'textfield',
    '#title' => t('City'),
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => 'Submit',
  );

  return $form;
}

After the first fieldset example, I hope this Drupal function is now fairly easy to read.

You can add other options to your Drupal fieldsets. Please see the Drupal Form API documentation for all of those options.

Drupal fieldset example - Summary

I hope this Drupal fieldset example has been helpful. As you can see, it's very easy to define a Drupal fieldset, and then add additional Drupal form elements to your fieldset.

drupal