Topic
Last updated August 22, 2017

Drupal provides a standard, secured method for module developers to add forms to a Drupal website. This method involves building render arrays in PHP and using predefined keys to specify various form element properties. The Form API describes properties for use in form arrays as well as base classes to extend, interfaces to implement, and methods for identifying, building, validating, and submitting the form.

The Configuration API also includes a special class for handling configuration settings forms, the ConfigFormBase class. See the Configuration API for Developers topic for more details about implementing configuration forms in Drupal 8.

Example tasks

  • Create custom forms in Drupal 8
  • Alter existing forms

Confidence

While there are many similarities to the Drupal 7 Form API, the Drupal 8 API is distinct, mostly in its implementation of object-oriented PHP. When browsing resources on the Form API, tutorials based on Drupal 7's Form API will likely need at least some minor adjustments in order to work in a Drupal 8 form.

Drupalize.Me resources

  • Render API Overview
    • Understand at a high level what the Render API is, when you'll encounter it, and the main components of the system. The Form API uses the Render API, so it's a good idea to familiarize yourself with the Render API before diving into building forms programmatically in Drupal.
  • What Are Render Arrays?
    • When you use the Form API to build a form you'll construct a render array. Learn about render arrays in this tutorial.
  • What Are Render Elements?
    • As you build a form with the Form API, you will make use of render elements. Learn about render elements in this tutorial.
  • Use #prefix and #suffix Properties to Wrap an Element
    • When you build a form, you can use #prefix and #suffix properties to wrap form elements. Learn more about this process in this tutorial.
  • Use Render Element Types in a Render Array
    • There are a bunch of existing render elements, most commonly Form API elements. In this tutorial, learn how to locate a list of existing render element types and use any of them when defining content with a render array.
  • Use #access to Show/Hide Elements in a Render Array
    • The #access property can be used an any element in a render array, including form elements, to control the visibility of that element and its children. Learn about how to make use of the #access property in this tutorial.
  • Create a Settings Form in a Module
    • Create a module containing default configuration, a settings form, and a menu link to the form.

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • Generating a Form with Drupal Console (kevinquillen.com)
    • Learn how to use Drupal Console to generate boilerplate code for a form in Drupal 8
  • Introduction to the Form API (drupal.org)
    • Learn about the new features of the Form API in Drupal 8; get an overview of the process of form building; learn about the classes and interfaces for use with forms; learn how to identify your form, build, validate, and submit it; and learn to alter an existing form with a hook.
  • Form generation (api.drupal.org)
    • The Drupal API page describes how to generate and manipulate forms and process form submissions.
  • Form and render elements (api.drupal.org)
    • This list contains all of the FormElement render elements that you can use in a form.
  • Change record: HTML5 support for form elements (drupal.org)
    • This is a list of HTML5 form elements that were introduced in Drupal 8, along with code usage examples.
  • Examples for Developers: Form API Example (cgit.drupalcode.org)
    • The Examples for Developers project provides code examples of various APIs in Drupal. You can download the project and browse the examples using your code editor or IDE of your choice.
  • Drupal 8 API: forms (jpstacey.info)
    • This article describes in detail how to implement the classes and interfaces related to forms in Drupal 8.
  • Implementing #autocomplete in Drupal 8 with Custom Callbacks (qed42.com)
    • How to implement autocomplete functionality in a form element, including utilizing a custom route and controller.
  • Theming form elements in Drupal 8 (thirdandgrove.com)
    • Learn about form-specific template files, preprocess functions, and how to customize the rendering of form elements.