Last updated April 29, 2020

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


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

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • A code-level Render API overview (
    • Overview of the Theme system and Render API.
  • Render API (
    • 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 (
    • 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 (
    • Comprehensive list of all core render elements.
  • Aha! Understanding and Using Render Arrays in Drupal 8 (
    • 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 (
    • An in-depth look at Drupal's request handling and rendering flow. Contains a helpful diagram linking all the pieces together.