I am new to Drupal 8 and it is hard to comprehend the documentation. I am required to make a custom module. I came across examples in creating custom modules, but I am having difficulty in making the correct return type. For example, consider the code snippet take from doc:

 * @file
 * Contains \Drupal\hello_world\Controller\HelloController.

namespace Drupal\hello_world\Controller;

use Drupal\Core\Controller\ControllerBase;

class HelloController extends ControllerBase {
  public function content() {
    return array(
        '#type' => 'markup',
        '#markup' => $this->t('Hello, World!'),

In this example, the controller is called when some page (defined in route) is visited. In this case an array is returned with #type and #markup, whose definition I cannot find anywhere. Similary consider another example:

namespace Drupal\acme\Controller;
use Drupal\Core\Controller\ControllerBase;
class DefaultController extends ControllerBase {
  public function hello($name) {
    // the {name} in the route gets captured as $name variable
    // in the function called
    return [
      '#theme' => 'hello_page',
      '#name' => $name,
      '#attached' => [
        'library' => [
          'acme/acme-styles', //include our custom library for this response

In this case, the return type is #theme, #name and #attached. These two code clearly shows different return type. As a beginner, I am having difficulty in understanding what to return from function as I cannot see those definitions in the documentation of ControllerBase class.

Where in the documentation are these tags defined and how do I use them in different scenarios? Thanks.


1 Answer 1


The return type of a Controller can be either a Response or a render array.

A render array is an array that you see in your code, and this is generally the best thing to return for a visible page as it provides the theme layer with opportunity to render into a template.

Render array types (#type) are defined in the Render Arrays docs page. See also the API docs for the RenderElement plugin I linked below.

The element type. If this array is an element, this will cause the default element properties to be loaded, so in many ways this is shorthand for a set of predefined properties which will have been arranged through a RenderElement plugin.

However the render array could also be defined to use a theme/template directly with (#theme), which is defined as

A single theme function/template which will take full responsibility for rendering this array element, including its children. It has predetermined knowledge of the structure of the element.

So the render array return for a Controller will depend on how you wish to structure the content that is displayed in the main content area.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.