Render array properties

A render array is a structured description of output. Keys starting with # are properties Drupal interprets; everything else is a child element. The render pipeline explains how arrays become HTML; this page lists the properties and element types you write by hand.

Example

$build = [
  '#type' => 'container',
  '#attributes' => ['class' => ['event-summary']],
  'title' => [
    '#type' => 'html_tag',
    '#tag' => 'h2',
    '#value' => $this->t('Upcoming events'),
  ],
  '#cache' => [
    'tags' => ['node_list:event'],
    'contexts' => ['user.permissions'],
  ],
];

Properties on every element

Property	Type	Description
#type	string	A render or form element type; pulls in that element’s defaults.
#theme	string	A theme hook that renders this array. Add __suggestion for a template suggestion.
#markup	string	A short HTML string, filtered for XSS. For trusted, larger output use #theme or a template.
#plain_text	string	Text that is HTML-escaped. Takes precedence over #markup.
#prefix / #suffix	string	Markup placed before / after the element’s output.
#weight	float	Sort order among siblings; lower renders first.
#attributes	array	HTML attributes, e.g. ['class' => ['foo'], 'id' => 'bar'].
#attached	array	Asset libraries, drupalSettings, HTTP headers, and html_head to attach.
#cache	array	Cacheability: keys, contexts, tags, max-age. See caching.
#access	bool | AccessResult	When FALSE, or when an AccessResult is not allowed (neutral or forbidden), the element and its children are not rendered. The result’s cacheability still bubbles.
#pre_render / #post_render	array	Callables that transform the element before / after rendering.
#lazy_builder	array	[callback, [args]] to build highly dynamic parts late, behind a placeholder.

Properties on form elements

Property	Type	Description
#title	string	The element’s label.
#description	string	Help text shown with the element.
#default_value	mixed	The value before the user edits it.
#required	bool	Marks the field required and adds validation.
#options	array	value => label choices for select, radios, checkboxes.
#ajax	array	Wire an element to an Ajax callback (callback, wrapper, event).
#value	mixed	A fixed value the user cannot edit (used by the value type).

Render element types

Set with #type. Each is a class under core's Render/Element directory.

#type	Renders
container	A wrapper div for grouping children.
html_tag	A single tag (#tag, #value, #attributes).
link	A link (#title, #url).
table	An HTML table (#header, #rows).
details	A collapsible <details> section.
fieldset	A grouped set of fields with a legend.
inline_template	A short Twig string rendered in place (#template, #context).
processed_text	Text run through a text format (#text, #format).
component	A single-directory component (#component, #props, #slots).

Form element types

#type	Input
textfield / textarea	Single- and multi-line text.
email / tel / url / number	HTML5 typed inputs with built-in validation.
select	A dropdown (#options).
radios / checkboxes	Grouped choices (#options).
checkbox	A single boolean.
date / datetime	Date and date-time pickers.
managed_file	An upload handled by the File module.
entity_autocomplete	Autocomplete for entity references (#target_type).
machine_name	A machine name derived from another field.
actions	The button group at the bottom of a form.
submit / button	Buttons.
value / hidden	Carry data without (and with) a hidden input.

Related

• Render pipeline for how these become HTML.
• Forms for building form arrays.
• The full element list and every property: the render API topic on api.drupal.org.