Get paid to write Drupal tutorials on WebWash

How to Create Powerful Container Paragraphs in Drupal 8

Want to learn more about Paragraphs? Then check out our online video course called “Build Edge-to-edge Sites using Paragraphs in Drupal 8“.

In the last Paragraphs tutorial, you were introduced to the module and we created a basic paragraph type called Content. We only skimmed the surface of what the module can really do. To utilize Paragraphs to its full potential you need to learn how to create a container paragraph type and nest paragraph items.

The concept of a container is fairly simple. It’s a paragraph type that has its own paragraph field on it and allows a user to nest paragraph items.

Below is an example of how it’ll be rendered.

Fig 1.0

In this tutorial, we’ll create a container paragraph called Banner, it’ll have two fields: image and paragraphs.

When a banner paragraph is created and an image is uploaded, the image will be displayed as a background style. Now, I do understand there’re multiple ways of doing this, but for simplicity we’ll set it using a background style on the paragraph element.

All nested paragraphs will be rendered inside the container and displayed with the background. If you want to add any other settings, i.e., parallax configuration, you would place it on the container paragraph.

Here is what the end product looks like on a Drupal site.

Fig 1.10

Getting Started

To save time, let’s reuse the paragraph type we created in the last tutorial. Don’t worry, you won’t have to reread the last tutorial again. Simply download this sandbox repo and enable it. Once the module has been enabled you should see the Content paragraph type.

Now make sure you have Paragraphs and Entity Reference Revisions installed.

Below are the Drush and Drupal Console commands to download and install:


$ drush dl paragraphs entity_reference_revisions
$ drush en paragraphs

Drupal Console:

$ drupal module:download paragraphs 8.x-1.0-rc4
$ drupal module:download entity_reference_revisions 8.x-1.0-rc4
$ drupal module:install paragraphs

Create Container Paragraph Type

The first bit of work that needs to be done is create the container paragraph type.

1. Go to Structure, “Paragraphs types” and click on “Add a Paragraphs type”.

Fig 1.1

2. Enter in Banner into Label and click on Save.

Fig 1.2

Add Fields to Container Paragraph Type

We created the Banner paragraph type, let’s now add two fields: Image and Paragraphs (the nested field).

1. Expand the Edit button and click on “Manage fields” on the Banner row.

Fig 1.3

2. Click on “Add field”, Select Image from “Add a new field” and add Image into Label. Then click on “Save and continue”.

Fig 1.4

3. Leave the “Field settings” page as the default and click on “Save field settings”.

4. On the Edit page, check the “Required field” checkbox, scroll to the bottom and click on “Save settings”.

So far we’ve done nothing ground breaking. All we did was create an image field and made it mandatory. Now let’s create a paragraph field which’ll be used to nest the paragraphs.

5. Click on “Add field” again, select Paragraph from “Add a new field” and enter Paragraphs into Label. Then click on “Save and continue”.

Fig 1.5

6. On the next page, leave it as the default then click on “Save field settings”.

7. On the edit page, scroll down to the list of paragraph types and select only Content. This will make sure the right paragraph is available. Then click on “Save settings”.

Fig 1.6

Field Widgets

So far we’ve simply created the fields, let’s now make sure the field widgets are configured.

1. Click on the “Manage form display” tab. If required, you can go ahead and change the widget settings. We’ll leave them as the default. Scroll to the bottom and click on Save.

Fig 1.7

Field Formatters

Finally, let’s quickly configure the field formatters.

1. Click on the “Manage display” tab.

2. Set the Label drop-down on the Paragraphs formatter to - Hidden -.

3. Make sure you move the Image field to the Disabled section. We’ll write a bit of code to add the image as a background to the paragraph. So this formatter isn’t needed.

4. The default settings on the paragraph formatter is fine so we won’t touch it. Scroll to the bottom and click on Save.

Fig 1.8

Implement Preprocess Hook

The final piece to this epic puzzle is the preprocess hook. As mentioned in the introduction the image will be added as a background style. We’ll need to implement this via a preprocess hook.

Copy the code below into a module or theme and replace the string “HOOK” with the actual theme or module name.

function HOOK_preprocess_paragraph__banner(&$variables) {
  $paragraph = $variables['paragraph'];
  if (!$paragraph->field_image->isEmpty()) {
    $image = $paragraph->field_image->entity->url();
    $variables['attributes']['style'][] = 'background-image: url("' . $image . '");';
    $variables['attributes']['style'][] = 'background-size: cover;';
    $variables['attributes']['style'][] = 'background-position: center center;';

Don’t forget to clear the site cache after adding the hook.

If the above code doesn’t work make sure that the machine name of the banner paragraph is simply banner and that the image field name is field_image. If the machine name for the paragraph or field is different then the code won’t work.

Create a Banner Paragraph

I’ll assume you already added the paragraph field on a content type. We learnt how to do that in the last tutorial. If this is new to you then please read the “Add Paragraph field” in the previous tutorial.

Go ahead and create an article with a paragraph field and create a banner. If everything has been setup, you should see the text in the Content paragraph displayed with the image as the background.

Fig 1.9


Creating a container paragraph is more advanced but the concept is simple. It simply groups a bunch of paragraphs together and that’s it. When creating these types of paragraphs, it’s good to stand back and map out all the possible paragraph types. Building these types of paragraphs can get very messy if the site requirements keep changing.

About the Author

Ivan is the founder of Web Wash and spends most of his time consulting and writing about Drupal. He's been working with Drupal for 10 years and has successfully completed several large Drupal projects in Australia.

Leave a Reply 7 comments

Chris Weber - January 26, 2016 Reply

In your video you could have using PhpStorm’s Drupal integration to help you figure out the name of the function to do the preprocess hook by just typing function then start typing preprocess. It would have discovered the name of the function you needed and replace hook for your module name for you.

    Ivan Zugec - January 26, 2016 Reply

    Thanks for the comment.

Patrick Koroma - February 19, 2016 Reply

I have been reading your tutorials since 2012.
Always simple and easy to understand – Thanks Mate.

Jim Rome - August 6, 2016 Reply

The default image field only accepts files from the editor’s disk, and uses absolute URLs on the displayed page. This breaks the display if you develop on an internal server. Is there a way around this?

    Ivan Zugec - August 8, 2016 Reply

    Sorry, I don’t know how to change the URL from absolute to relative.

    But as a workaround look at Stage file proxy module,

    The module lets you have a local site but Drupal will download and cache the images from the production site. So you won’t have to download the whole files directory.

Jim Rome - August 10, 2016 Reply

This does not seem to work in IE11 (left). It does work in Edge (right)

    Ivan Zugec - August 10, 2016 Reply

    That’s a shame, you’ll have to debug this further.

Leave a Reply: