Using Paragraphs in Drupal 8

Post by Paul B Picture of Paul B
Reading time 3 mins clock

When we received the new designs for the Ixis site it was evident that they contained separate design elements which were shared across several pages, from the homepage to departmental landing pages to the “About us” page. We thought this was a perfect use case for the Paragraphs module, which allows site editors to "choose on-the-fly between predefined Paragraph Types… instead of putting all of their content in one WYSIWYG body field."

Most content types on the new Ixis site contain a Paragraphs field. An editor can create multiple Paragraphs of any defined type and sort them to specify the elements and layout of the node's content.

Adding text and testimonial paragraphs

Paragraph types can be anything from a simple text block or image to a complex and configurable slideshow. Paragraph types are essentially fieldable entities and the Paragraphs module allows the creation of these types. Each defined type can have it’s own set of relevant fields, all added via the Drupal UI and exporting to config.

So, to support the elements outlined in our page designs we added Paragraph types for:

  • Call to action - areas of bold background colour and large text;
  • Download - a downloadable asset or file;
  • Gallery - a gallery list of images;
  • Image - a single, responsive image;
  • Testimonial - a quote or testimonial;
  • Text - basic, filtered HTML edited with CKEditor;
  • Text with Callout - regular body text coupled with a styled "callout";
  • Twitter - an embedded Twitter widget;
  • Video - an embedded video from a 3rd-party site such as YouTube.

All these Paragraph types give editors some flexibility and choice when authoring a page designed with several of these elements.


The rendered output of Paragraphs entities can be altered using a paragraph.html.twig file in the site’s theme. For example:

  set classes = [
    'paragraph--type--' ~ paragraph.bundle|clean_class,
    view_mode ? 'paragraph--view-mode--' ~ view_mode|clean_class,
    cta_style ? 'cta-style--' ~ cta_style|clean_class,
<div {{ attributes.addClass(classes) }}>
  <div class="container">
    {% block paragraph_content %}
      <div class="row">
        <div class="col-sm-12">
          {{ content }}
    {% endblock paragraph_content %}

The rendered output of each individual Paragraph type can also be affected using a suggested Twig template, for example we have paragraph--testimonial.twig.html for appropriately rendering a testimonial quote and cited author.

In some places we’ve used a field combined with a preprocess to provide multiple variations of the same paragraph. You can see this in action above with the cta_style variable which gives us a standard or inverted dark style for Call to action paragraphs.

Content Migration

During the initial content migration, we migrated directly into a Text Paragraph in the new Paragraphs field for some content types such as blog posts. To do this, we needed a new process plugin:

 * Saves D6 Page Body field to D8 Page Paragraph (Textarea) field.
 * @MigrateProcessPlugin(
 *   id = "node_paragraph_textarea"
 * )
class NodeParagraphTextarea extends ProcessPluginBase {

We used a slightly modified version of the example plugin in this article by Amit Goyal. Then in our migration.d6.node__blog.yml we removed:

  plugin: migration
    migration: d6_filter_format
    source: format
body/value: body
body/summary: teaser

and replaced with the new process plugin to instead migrate the source body into the Paragraphs field:

  plugin: node_paragraph_textarea
  source: body

In summary, Paragraphs is a great alternative to a single WYSIWYG editor for site editors who want to be able to lay out complex pages combining text, images, video, audio, quotes or any other advanced component. Here's some further reading:


Paul B

Development Manager

Manager of all things development related at Ixis. Looking after the clients from discovery time to delivery of complete web builds.

Add new comment

Share this article

Sign up to our newsletter!

Our thoughts

Let's work together

Get in touch and find out how we can empower your organisation.
Back to top