Module Development

Add Cache Metadata to Render Arrays for Drupal 8, 9, 10, and 11

The individual items that make up the content of a page impact the cacheability of that page. In order for Drupal's cache and external caches to better understand how the content varies on a page, module developers use the #cache render element property. The #cache property defines cacheability metadata for individual elements in a render array.

Additionally, these Render API elements can become fairly complex. The calculation of what the final HTML output should look like often involves looking up content in the database, checking multiple conditions, maybe querying an external API, and various other tasks. This can cause turning a render array into HTML to become quite expensive. In order to speed up this process, the Render API will cache the generated HTML for each element and reuse it on future requests whenever possible -- but only if you tell it to do so.

In this tutorial, we'll look at:

  • How render caching impacts the performance of a page
  • Defining the cacheability of an item with cache tags, cache contexts, and cache max-age
  • Examples of using the #cache property in a render array

By the end of this tutorial you should know how, and when, to use the #cache property when defining render arrays.