Render Array Builder

Drupal Render Array Builder — How to Use

Drupal's render API uses render arrays — PHP associative arrays with special keys prefixed by # — to describe every piece of output before it is converted to HTML. Instead of concatenating HTML strings, you build a structured array that Drupal's theme system renders at the appropriate time in the request lifecycle.

Common render array properties include #type (the element type), #markup (raw HTML), #theme (the theme hook to call), #attached (CSS/JS libraries), and #cache (caching metadata). Always prefer render arrays over raw HTML strings for security, cacheability, and theme override support.

Where Render Arrays Are Used

• Controllers — Return a render array from a route controller instead of a Response object for automatic theming.
• Blocks — The build() method of a block plugin must return a render array.
• Form API — Every form element is a render array with #type set to the element type.
• Preprocessors — Attach render arrays to template variables in hook_preprocess_HOOK().

Security: #markup vs #plain_text

Use #markup only for trusted HTML that has already been sanitised. For user-supplied strings, use #plain_text instead — Drupal will escape it automatically. Never pass unsanitised user input to #markup.