Layout Paragraphs
layout_paragraphs
Provides an intuitive drag-and-drop interface for building flexible layouts with Paragraphs using Drupal's Layout API.
Overview
Layout Paragraphs provides an intuitive drag-and-drop experience for building flexible layouts with Paragraphs. The module was designed from the ground up with paragraphs in mind, and works seamlessly with existing paragraph reference fields.
Key features include an intuitive drag-and-drop interface, flexible configuration where site admins choose which paragraphs to use as "layout sections" and which layouts should be available for each, and compatibility with Drupal 10 and 11.
The module leverages Drupal's Layout API for building layouts and uses the paragraphs behaviors API for storing layout data. Unlike Layout Builder in Drupal core, Layout Paragraphs is not a site building tool but rather an authoring tool designed specifically for content creators.
Layout Paragraphs supports nested layouts, quick toggling between different layouts within a section without deleting content, and provides a "What You See Is What You Get" authoring experience when configured to use the "Layout Paragraphs Builder" field formatter.
Install
composer require 'drupal/layout_paragraphs:^2.1'
Features
- Intuitive drag-and-drop interface for arranging paragraphs within layouts
- Works with existing paragraph reference fields without migration
- Leverages Drupal's Layout API and Layout Discovery for layout definitions
- Paragraph Behaviors API integration for storing layout data
- Support for nested layouts with configurable nesting depth
- Quick layout switching without content deletion
- WYSIWYG authoring experience with Layout Paragraphs Builder formatter
- Component duplication support
- Translation support including asymmetric translations
- Modal-based component editing with configurable dimensions
- Visual layout selection with thumbnail previews
- Field cardinality support
- Tempstore-based editing for unsaved changes
Use Cases
Landing Page Builder
Create flexible landing pages by defining a 'Section' paragraph type with the Layout Paragraphs behavior enabled. Select layouts like 2-column, 3-column, or full-width. Content editors can then drag-and-drop other paragraph types (Hero, CTA, Cards, Text blocks) into layout regions to build visually rich pages without developer assistance.
Article with Rich Content
Enhance article content by allowing authors to insert layout sections within the body. For example, an author can add a 2-column section mid-article to display an image alongside related text, then continue with regular content below. This provides magazine-style layout capabilities within standard content.
Product Showcase Pages
Build product pages with multiple sections: a hero section with product image and title, a features section with 3-column layout for feature highlights, a full-width video section, and a 2-column comparison chart. Each section can use different layouts while maintaining a cohesive page structure.
Reusable Content Components
Combined with the Layout Paragraphs Library submodule, create reusable content blocks like standardized CTAs, footer sections, or promotional banners. Content editors can build a component once, promote it to the library, then reuse it across multiple pages with the option to unlink and customize individual instances.
Multi-language Content Sites
For sites with content in multiple languages, configure the paragraph reference field as translatable to enable asymmetric translations. Each language version can have different paragraph arrangements and content while sharing the same base structure.
Restricted Editor Workflows
Use the Layout Paragraphs Permissions submodule to create tiered editing permissions. Allow basic editors to add and edit content within existing layouts, while restricting layout reordering and duplication to senior editors or administrators.
Tips
- Use the 'Preview view mode' widget setting to create a simplified display specifically for the builder interface, hiding complex field formatting that might slow down editing.
- Set 'Maximum nesting depth' to 0 initially, then increase only if you specifically need nested layouts - this keeps the interface simpler for content editors.
- Create dedicated paragraph types for layout sections (e.g., 'Section', 'Container') and keep them separate from content paragraph types for clearer organization.
- Use the 'Require paragraphs to be added inside a layout' option when you want to enforce a consistent page structure.
- Consider using different form display modes for the builder (form_display_mode setting) to show only essential fields during inline editing.
- The Layout Paragraphs Builder formatter (Experimental) provides the best authoring experience as it allows editing directly on the view page without navigating to the edit form.
Dependencies
Related Projects
Core integration - Layout Paragraphs extends Paragraphs functionality with layout capabilities using the Paragraphs Behaviors API.
Uses Drupal core's Layout Discovery to find and use available layouts from themes and modules.
Via the layout_paragraphs_library submodule, provides ability to promote paragraphs to reusable library items.
Full support for content translation including asymmetric translations when the reference field is configured as translatable.
Handles paragraph duplication correctly, updating parent UUID references when paragraphs are replicated.
Test dependency indicates compatibility with Block Field module for embedding blocks within paragraphs.
Compatibility handling for inline entity form submit triggers.
Admin Pages
| Title | Path | Description |
|---|---|---|
| Layout Paragraphs Labels | /admin/config/content/layout_paragraphs/labels |
Configure site-wide settings for Layout Paragraphs field widgets including label visibility and behavior fieldset positioning. |
| Layout Paragraphs Sections | /admin/config/content/layout_paragraphs/sections |
Configure which paragraph types can be used as layout sections and which layouts are available for each. |
| Layout Paragraphs Modal Settings | /admin/config/content/layout_paragraphs/modal-settings |
Configure the dimensions and behavior of modal dialogs used for editing paragraphs. |
Hooks
| Hook | Description |
|---|---|
hook_form_layout_paragraphs_component_form_alter |
Alter the Layout Paragraph component form (paragraph edit form within the builder). |
hook_preprocess_layout_paragraphs_builder |
Preprocess the Layout Paragraphs Builder element. Modify the builder interface. |
hook_preprocess_layout_paragraphs_builder_controls |
Alter the component controls UI (move up, move down, edit, delete, duplicate buttons). |
hook_entity_view_alter |
Use with $build['#layout_paragraphs_component'] to modify paragraph rendering within Layout Paragraphs. UI elements can be modified via $build['drupalSettings']['lpBuilder']['uiElements']. |
Troubleshooting
Ensure the Dragula library is properly installed. Check that either: (1) the library exists at /libraries/dragula/dist/dragula.min.js, (2) it was installed via Composer with Asset Packagist, or (3) the CDN fallback is not being blocked by your CSP. Clear Drupal cache after installing the library.
Verify that the paragraph type has the 'Layout Paragraphs' behavior enabled at Structure > Paragraph types > [type] > Edit > Behavior. Ensure at least one layout is selected in the 'Available Layouts' setting for that behavior.
If the paragraph reference field is not marked as translatable, adding/removing paragraphs is disabled in translation mode to prevent data inconsistency. To enable asymmetric translations (different paragraphs per language), make the reference field translatable at the field settings level.
Adjust modal dimensions at Administration > Configuration > Content authoring > Layout Paragraphs settings > Modal Settings. Set width to '90%' and height to 'auto' with autoresize enabled for best results.
This is by design. Paragraph types that function as layout sections (have Layout Paragraphs behavior enabled) cannot be promoted to the library because they contain structural information that may not transfer correctly.
Layout Paragraphs uses tempstore to preserve changes during editing. However, if you navigate away without saving the parent entity, changes will be lost. Always save the node/entity after making layout changes.
Security Notes
- Access to Layout Paragraphs operations is controlled by standard Drupal entity access (create, update, delete permissions on paragraphs and the host entity).
- The builder access service checks both field-level access and entity-level access before allowing operations.
- Form tags, name attributes, and required attributes are stripped from rendered paragraph previews to prevent form hijacking when the builder is rendered within another form.
- The Layout Paragraphs Permissions submodule provides additional granular permissions for specific operations like reordering and duplicating.