Topic
Last updated August 25, 2017

The Render API consists of two parts: structured arrays that provide data and hints about how that data should be rendered, and a rendering pipeline that can be used to render these arrays into various output formats. It is used for all content output for display by Drupal, as well as for describing and controlling forms that collect user input, and directing how that input is handled.

The Render API serves as the glue between modules which store and manipulate data on the backend, and themes that display that data to users. As such, it's important for both theme and module developers to understand at least the basics of how the Render API works, the difference between elements and properties in a render array, and the concept of callback functions.

Example tasks

  • Define content, or forms, to be displayed in a module
  • Alter content, or a form, provided by another module
  • Discover which Twig template is used to theme an element in a render array
  • Alter existing render arrays in order to change the appearance of content when it is displayed

Confidence

We don't anticipate any major changes to how the Render API works in the Drupal 8 cycle. Writing a render array hasn't changed much between Drupal 7 and 8. The concepts like elements and properties are still the same, with the major difference being that render elements are now implemented as plugins.

Drupalize.Me resources

  • Render API Overview
    • Get an overview of what the Render API is used for, all its pieces, and how they all fit together.
  • What Are Render Arrays?
    • Understand when, and how, to use render arrays in your code.
  • What Are Render Elements?
    • Learn about the use-case for render elements and how to use them when defining a render array.
  • Render Pipeline
    • Understand the process that Drupal goes through to convert a request from a user's browser or other client into a value response, and how that relates to the Render API.
  • Forms (Form API)
    • The Form API uses render arrays as part of the process for defining a form for collecting user input via a module.

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • A code-level Render API overview (api.drupal.org)
    • Overview of the Theme system and Render API.
  • Render API (drupal.org)
    • Documentation that goes into more depth on specific aspects of the Render API. Useful for understanding how these more complex parts work.
  • Examples for Developers (drupal.org)
    • The Examples project contains a Form API and a Render API example, both of which provide code samples that demonstrate the Render API in action.
  • Form and render elements (api.drupal.org)
    • Comprehensive list of all core render elements.
  • Aha! Understanding and Using Render Arrays in Drupal 8 (events.drupal.org)
    • Presentation from DrupalCon NOLA that provides a good overview of the Render API, its use case, and a little history.
  • The Drupal 8 render pipeline (drupal.org)
    • An in-depth look at Drupal's request handling and rendering flow. Contains a helpful diagram linking all the pieces together.