Paragraphs

Enables creation of structured content using reusable paragraph components that can be combined on content pages.

paragraphs

240,611 sites

434

drupal.org

content field entity paragraphs components structured content landing page page builder layout

Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10 v8.x-1.19

composer require 'drupal/paragraphs:8.x-1.19'

Drupal 9 v8.x-1.17

composer require 'drupal/paragraphs:8.x-1.17'

Overview

The Paragraphs module provides a powerful field type that allows users to create structured, reusable content components. Instead of relying on a single WYSIWYG editor, content creators can build pages by adding multiple paragraph types, each with its own fields and display settings.

Paragraphs are ideal for landing pages, complex layouts, and any content that benefits from a modular, component-based approach. Each Paragraph type is a bundle that can contain any Drupal fields, giving site builders complete flexibility in defining content structures.

The module integrates with the Entity Reference Revisions module to maintain revision history and supports multilingual content through Drupal's translation system. It also provides a sophisticated widget interface with drag-and-drop reordering, collapse/expand functionality, and duplicate features.

Features

Create custom Paragraph types with any combination of Drupal fields
Add multiple Paragraphs to any entity using the Entity Reference Revisions field type
Two field widget options: Stable (recommended) with full features and Legacy for backward compatibility
Drag & drop reordering of paragraphs, including nested paragraph support
Behavior plugin system for adding custom functionality to paragraph types
Multiple add modes: Dropdown button, Select list, Buttons, or Modal form
Configurable edit modes: Open, Closed, or Closed with nested expansion
Summary and Preview display modes when paragraphs are collapsed
Duplicate paragraph feature for quickly copying existing content
Convert feature for transforming paragraphs between compatible types
Collapse/Edit all actions for managing multiple paragraphs efficiently
Add above feature for inserting paragraphs at specific positions
Per-paragraph type icons for visual identification
Full revision support through Entity Reference Revisions integration
Multilingual paragraph translation support
Migration support from Drupal 7 Paragraphs and Field Collection modules
Unpublished paragraph visibility control

Use Cases

Landing Page Builder

Create diverse landing pages by combining paragraph types like Hero Banner, Feature Grid, Testimonial Slider, Call-to-Action, and Content Blocks. Content editors can build unique page layouts without developer intervention by selecting and arranging different paragraph types.

Blog Post with Rich Media

Build article content types with paragraphs for Text Sections, Image Galleries, Embedded Videos, Pull Quotes, and Related Content blocks. Authors can intersperse media throughout their articles in any order.

Product Showcase

Create product pages with paragraphs for Product Specifications, Feature Highlights, Image Carousels, Customer Reviews, and Related Products. Each section can have its own layout and styling.

Reusable Content Components

Use the Paragraphs Library submodule to create reusable components like company address blocks, disclaimer text, or promotional banners that can be shared across multiple pages and updated in one place.

Multi-column Layouts

Create paragraph types that contain nested paragraph fields (e.g., a Two Column Layout paragraph containing left and right column paragraphs), enabling complex nested layouts with drag-and-drop reordering.

Event Listings

Build event content with paragraphs for Event Details, Schedule/Agenda items, Speaker Profiles, Venue Information, and Registration forms. Each event can have a unique combination of information sections.

Tips

Use the 'Closed' edit mode with 'Summary' closed mode for fields with many paragraphs to improve form performance and usability
Set a default paragraph type to pre-populate new content with commonly used paragraph types
Use paragraph type icons to help content editors quickly identify paragraph types in the widget
Enable the 'Add above' feature when using Modal form add mode for precise paragraph positioning
Consider using the Paragraphs Library submodule for content that needs to appear on multiple pages
Use behavior plugins to add consistent styling options (like background colors or width settings) across paragraph types
Set appropriate Field UI form modes for paragraphs to control which fields appear in different contexts
Use the 'Closed mode threshold' setting to keep short forms open while collapsing longer ones
Enable the Paragraphs Type Permissions submodule when different roles need different paragraph creation abilities
Test paragraph content with Content Translation to ensure proper multilingual workflow

Dependencies

Entity Reference Revisions Required

File Core Required

Related Projects

Entity Reference Revisions

Required dependency. Paragraphs uses entity reference revisions fields to maintain revision history and parent-child relationships.

Content Translation Core

Paragraphs supports multilingual content by translating paragraph fields within the parent entity. The paragraph field itself should NOT be translatable, but individual fields within paragraph types should be marked translatable.

Field Group

When enabled, field groups defined on paragraph form displays are automatically rendered within the paragraph widget.

Replicate

When enabled, the Replicate module's cloning functionality is used for duplicating paragraphs, providing better handling of complex field types.

Diff

Integration for displaying differences between paragraph revisions.

Inline Entity Form

Test integration for inline entity form compatibility.

Block Field

Paragraph summaries include block admin labels when block_field fields are present.

Entity Usage

Required by Paragraphs Library submodule for tracking usage of library items across the site.

Technical Details

Paragraph types /admin/structure/paragraphs_type

Lists all available Paragraph types with options to add, edit, delete, and manage fields for each type. Each Paragraph type represents a reusable content component with its own set of fields.

Add Paragraph type /admin/structure/paragraphs_type/add

Form to create a new Paragraph type with label, machine name, icon, description, and behavior plugins configuration.

Edit Paragraph type /admin/structure/paragraphs_type/{paragraphs_type}

Edit an existing Paragraph type's settings including label, icon, description, and behavior plugins.

Paragraphs settings /admin/config/content/paragraphs

Global configuration settings for the Paragraphs module.

Administer Paragraphs types

Allow to define the existing Paragraphs types and their Fields

Edit behavior plugin settings

Users with this permission can edit behavior plugin settings on Paragraphs behavior instance

View unpublished paragraphs

Users with this permission can view paragraphs that are unpublished

Administer Paragraphs settings

Administer Paragraphs settings

hook_paragraphs_behavior_info_alter

Alters the information provided in ParagraphsBehavior plugin annotations. Allows modules to modify behavior plugin definitions.

hook_paragraphs_widget_actions_alter

Alters the actions available in the Paragraphs widget. Allows adding custom buttons and dropdown actions for paragraph items.

hook_paragraphs_conversion_alter

Alters paragraphs after conversion between types. Fired once per converted paragraph entity for post-conversion modifications.

Paragraphs field is marked as translatable causing data loss

Never mark the Entity Reference Revisions field that references paragraphs as translatable. Instead, mark individual fields within paragraph types as translatable. See the multilingual configuration instructions in README.txt.

Drag and drop not working

Ensure you are using Drupal 8.8.0+ which includes the required Sortable library in core. The drag & drop feature requires the Stable widget (not Legacy).

Behavior plugins not appearing on paragraph type form

Behavior plugins only appear if they are applicable to the paragraph type. Check that the plugin's isApplicable() method returns true for your paragraph type.

Orphaned paragraphs appearing in database

Paragraphs are normally deleted when their parent entity is deleted. Orphaned paragraphs can occur from interrupted saves or bugs. Use entity cleanup modules or database queries to identify and remove orphans.

Widget settings not saving on field configuration

Ensure the widget type is set to 'Paragraphs (stable)' or 'Paragraphs Legacy', not other entity reference widgets which are not compatible with paragraphs.

The 'administer paragraphs types' permission grants significant access and should only be given to trusted administrators
The 'view unpublished paragraphs' permission may expose draft content; assign carefully
When using Paragraphs Library, consider that library items are shared - changes affect all instances
Paragraph access inherits from the parent entity; ensure parent entity access controls are appropriate