When should the "container" form element be used? The System module defines the container form element, but that form element is not documented in the Form API Reference.

When should that form element be used? What is its purpose?
It looks like it can be used when you want to wrap a part of the form in a div, for example to be able to add some classes to it.

Some examples from core are the following:


field_default_form()

// Also aid in theming of field widgets by rendering a classified container.
$addition[$field_name] = array(
  '#type' =&gt; 'container',
  '#attributes' =&gt; array(
    'class' =&gt; array(
     'field-type-' . drupal_html_class($field['type']),
     'field-name-' . drupal_html_class($field_name),
     'field-widget-' . drupal_html_class($instance['widget']['type']),
    ),
  ),
  '#weight' =&gt; $instance['widget']['weight'],
);

node_filter_form()

$form['filters']['status'] = array(
  '#type' =&gt; 'container',
  '#attributes' =&gt; array('class' =&gt; array('clearfix')),
  '#prefix' =&gt; ($i ? '&lt;div class="additional-filters"&gt;' . t('and where') . '&lt;/div&gt;' : ''),
);
$form['filters']['status']['filters'] = array(
  '#type' =&gt; 'container',
  '#attributes' =&gt; array('class' =&gt; array('filters')),
);

search_form()

$form['basic'] = array(
  '#type' =&gt; 'container',
  '#attributes' =&gt; array('class' =&gt; array('container-inline')),
);



Forms in Drupal 6 often used #prefix and #suffix on the first/last element to do this; this is a lot better because it is easier to add additional items or move them around.

I could use this in a few places in my own contributed modules, actually. ;)