Module Development

Form Element Reference for Drupal 8, 9, 10, and 11

Drupal core provides a couple dozen different input #type elements that can be added to forms. This includes one for every standard HTML5 input element, and some Drupal-specific ones that encapsulate more complex interactions like uploading files. But how can you know what elements exist? Where do you find information about what Render API properties each element uses?

In this tutorial we'll:

  • Define what FormElements are and how they relate to the Render API
  • Find a list of all available input element types, additional documentation and usage examples
  • See examples of the most common element types

By the end of this tutorial you should be able to discover the different types of elements you can add to a $form array and find usage examples for each.

Goal

Provide a reference page for quickly finding information about available form element types.

Prerequisites

Element types

List of form element types:

  • Button (#type => 'button'): Provides an action button form element.
  • Checkbox (#type => 'checkbox'): Provides a form element for a single checkbox.
  • Checkboxes (#type => 'checkboxes'): Provides a form element for a set of checkboxes.
  • Color (#type => 'color'): Provides a form element for choosing a color.
  • Date (#type => 'date'): Provides a form element for date selection.
  • Datelist (#type => 'datelist'): Provides a datelist element which consists of a set of select elements pre-configured for choosing a date.
  • Datetime (#type => 'datetime'): Provides a datetime element.
  • Email (#type => 'email'): Provides a form input element for entering an email address.
  • EntityAutocomplete (#type => 'entity_autocomplete'): Provides an entity autocomplete form element.
  • File (#type => 'file'): Provides a form element for uploading a file.
  • Hidden (#type => 'hidden'): Provides a form element for an HTML 'hidden' input element.
  • ImageButton (#type => 'image_button'): Provides a form element for a submit button with an image.
  • Item (#type => 'item'): Provides a display-only form element with an optional title and description.
  • LanguageConfiguration(#type => 'language_configuration'): Defines an element for language configuration for a single field.
  • LanguageSelect (#type => 'language_select'): Provides a form element for selecting a language.
  • MachineName (#type => 'machine_name'): Provides a machine name form element that consists of a textfield for human-readable input, and another textfield that automatically generates a machine name based on the input.
  • ManagedFile (#type => 'managed_file'): Provides an AJAX/progress aware widget for uploading and saving a file. Files are saved as entities and managed by Drupal.
  • Number (#type => 'number'): Provides a form element for numeric input, with special numeric validation.
  • Password (#type => 'password'): Provides a form element for entering a password, with hidden text.
  • PasswordConfirm (#type => 'password_confirm'): Provides a form element for double-input of passwords.
  • PathElement (#type => 'path'): Provides a form element to enter a path which can be optionally validated and stored as either a \Drupal\Core\Url value object or an array containing a route name and route parameters pair.
  • Radio (#type => 'radio'): Provides a form element for a single radio button.
  • Radios (#type => 'radios'): Provides a form element for a set of radio buttons.
  • Range (#type => 'range'): Provides a slider for input of a number within a specific range.
  • Search (#type => 'search'): Provides an HTML5 input element with type of "search".
  • Select (#type => 'select'): Provides a form element for a drop-down menu or scrolling selection box.
  • Submit (#type => 'submit'): Provides a form submit button.
  • Table (#type => 'table'): Provides a render element for a table.
  • Tableselect (#type => 'tableselect'): Provides a form element for a table with radios or checkboxes in left column.
  • Tel (#type => 'tel'): Provides a form element for entering a telephone number.
  • Textarea (#type => 'textarea'): Provides a form element for input of multiple-line text.
  • Textfield (#type => 'textfield'): Provides a one-line text field form element.
  • Token (#type => 'token'): Stores token data in a hidden form field. This is generally used to protect against cross-site forgeries. A token element is automatically added to each Drupal form, so you generally do not need to add one yourself.
  • Url (#type => 'url'): Provides a form element for input of a URL, with built in validation for URL formatting.
  • Value (#type => 'value'): Provides a form element for storage of internal information.
  • VerticalTabs (#type => 'vertical_tabs'): Provides a render element for vertical tabs in a form.
  • Weight (#type => 'weight'): Provides a form element for input of a weight. Weights are integers used to indicate ordering, with larger numbers later in the order.

Form elements explained

The buildForm(array $form, FormStateInterface $form_state) method of a form controller returns an associative array, usually named $form, that defines the markup and input elements your form is composed of. Each element in the array consists of a set of properties, and possible nested child elements, that define the details Drupal uses to generate the HTML version of the form.

Example form render array

$form['phone_number'] = array(
  '#type' => 'tel',
  '#title' => $this->t('Example phone'),
  '#default_value' => '867-5309',
);

These arrays are known as render arrays, and it's a good idea to be familiar with their structure, and the related terminology.

Render arrays that define a form can make use of all standard Render API RenderElement types, as well as the Form API-specific FormElement types. The latter are used primarily to define input and control elements on a form. These are used for the #type key of elements in a $form array, and also dictate which additional properties can be used for that element.

In addition to the set of default properties available for all RenderElement elements, FormElement elements all have the following properties, as well as element-type-specific properties.

Type Description
#after_build (array) Array of callables or function names, which are called after the element is built. Arguments: $element, $form_state.
#ajax (array) Array of elements to specify Ajax behavior. See the Ajax API topic for more information.
#array_parents (string, read-only) Array of names of all the element's parents (including itself) in the render array. See also #parents, #tree.
#default_value Default value for the element. See also #value.
#description (string) Help or description text for the element. In an ideal user interface, the #title should be enough to describe the element, so most elements should not have a description. If you do need one, make sure it is translated. If it is not already wrapped in a safe markup object, it will be filtered for XSS safety.
#disabled (bool) If TRUE, the element is shown but does not accept user input.
#element_validate (array) Array of callables or function names, which are called to validate the input. Arguments: $element, $form_state, $form.
#field_prefix (string) Prefix to display before the HTML input element. Should be translated, normally. If it is not already wrapped in a safe markup object, it will be filtered for XSS safety.
#field_suffix (string) Suffix to display after the HTML input element. Should be translated, normally. If it is not already wrapped in a safe markup object, will be filtered for XSS safety.
#input (bool, internal) Whether or not the element accepts input.
#parents (string, read-only) Array of names of the element's parents for purposes of getting values out of $form_state. See also #array_parents, #tree.
#process (array) Array of callables or function names, which are called during form building. Arguments: $element, $form_state, $form.
#processed (bool, internal) Set to TRUE when the element is processed.
#required (bool) Whether or not input is required on the element.
#states (array) Information about JavaScript states, such as when to hide or show the element based on input on other elements.
#title (string) Title of the form element. Should be translated.
#title_display (string) Where and how to display the #title. Possible values: before: Label goes before the element (default for most elements). after: Label goes after the element (default for radio elements). invisible: Label is there but is made invisible using CSS. attribute: Make it the title attribute (hover tooltip).
#tree (bool) TRUE if the values of this element and its children should be hierarchical in $form_state; FALSE if the values should be flat. See also #parents, #array_parents.
#value_callback (callable) Callable or function name, which is called to transform the raw user input to the element's value. Arguments:$element, $input, $form_state.

You can find a complete list of the render element types provided by Drupal core at https://api.drupal.org/api/drupal/elements. Pay special attention to FormElement types, and note that you can click through to the class that defines the element type for additional documentation on element type specific properties and in most cases a usage example.

Recap

In this tutorial we listed all the form element types provided by Drupal core and linked to the documentation for each. We also looked at the list of properties that are available for all form elements regardless of type. View the documentation for each individual element type to see documentation of type-specific properties.

Further your understanding

  • Check out the list of properties that are available for all render element types. Remember, those also apply to form elements.

Additional resources

On this page