Paragraph Blocks
Enables placing individual paragraph field values as separate blocks in Layout Builder.
paragraph_blocks
Install
composer require 'drupal/paragraph_blocks:^4.1'
Overview
The Paragraph Blocks module extends Drupal's Layout Builder functionality by allowing each value of a multi-value paragraph field to be placed as an individual block. This provides powerful flexibility when designing page layouts with paragraphs.
The module adds an "admin title" field to paragraph entities, which is used to identify paragraphs when selecting blocks in Layout Builder. This makes it easy to distinguish between multiple paragraph items, especially when using per-entity layout overrides.
Key capabilities include automatic synchronization of Layout Builder configuration when paragraphs are reordered or deleted, integration with Content Moderation for managing pending revisions, support for the Paragraphs Library module, and Token support for dynamic admin title generation.
Features
- Places each value of multi-value paragraph fields as individual blocks in Layout Builder
- Adds an admin title field to paragraph entities for identification in the Layout Builder UI
- Automatically updates Layout Builder block configuration when paragraphs are reordered or deleted
- Supports per-entity type and per-entity Layout Builder configurations
- Integrates with Content Moderation to support pending revisions and draft content
- Supports the Paragraphs Library module for reusable paragraph items
- Allows configuring default admin titles per paragraph type with Token support
- Provides option to enable/disable paragraph blocks per paragraph field
- Configurable maximum cardinality for paragraph blocks display
- Option to suppress label field during block placement in Layout Builder
Use Cases
Creating flexible landing pages
Use paragraph blocks to build landing pages where each section (hero, features, testimonials, etc.) is a separate paragraph that can be independently positioned in different layout regions using Layout Builder.
Per-page layout customization
Enable 'Allow each content item to have its layout customized' in Layout Builder to let editors rearrange paragraph blocks differently on each page, using admin titles to identify each paragraph in the interface.
Sidebar content management
Place specific paragraph items in sidebar regions while keeping others in the main content area, all managed through the same paragraph field on the content type.
A/B testing content sections
Easily reposition or hide specific paragraph sections across different pages by managing their placement in Layout Builder without modifying the underlying content.
Reusable content with Paragraphs Library
Combine with the Paragraphs Library module to create reusable content blocks that can be placed via Layout Builder while maintaining a single source of truth.
Tips
- Set meaningful default admin titles on paragraph types using tokens like [paragraph:field_title] to automatically generate descriptive block names
- Use the 'Suppress label field' option to streamline the block placement interface for content editors
- For sites with many paragraph types, keep 'Display individual paragraph blocks in the UI' disabled to maintain performance
- When using Content Moderation, paragraph blocks will automatically show the latest revision including draft content in preview mode
- The admin title field is translatable and revisionable, supporting multilingual and revision-aware workflows
Technical Details
Admin Pages 1
/admin/config/content/paragraph_blocks
Configure global settings for the Paragraph Blocks module, including the maximum number of paragraph blocks to display and UI behavior options.
Hooks 8
hook_entity_base_field_info
Adds the 'admin_title' base field to paragraph entities. This field stores a user-defined title for identifying paragraphs in Layout Builder.
hook_plugin_filter_TYPE__CONSUMER_alter (layout_builder)
Filters and relabels paragraph block definitions in the Layout Builder 'Add Block' interface. Removes unavailable paragraph blocks and updates admin labels.
hook_field_widget_info_alter
Replaces the default entity_reference_paragraphs widget class with ParagraphBlocksInlineParagraphsWidget to customize admin title display behavior.
hook_entity_type_alter
Replaces the default Paragraph entity class with ParagraphBlocksEntity to add admin title support methods.
hook_form_field_config_edit_form_alter
Adds an 'Enable Paragraph Blocks' checkbox to paragraph field configuration forms, allowing per-field control of paragraph blocks functionality.
hook_entity_presave
Updates Layout Builder configuration when entities with paragraph fields are saved. Handles paragraph reordering and deletion to maintain layout integrity.
hook_form_paragraphs_type_form_alter
Adds a 'Default admin title' field to paragraph type configuration forms. Supports Token patterns for dynamic title generation.
hook_paragraph_create
Sets the default admin title on newly created paragraphs based on the paragraph type's configured default.
Troubleshooting 5
Ensure the paragraph field has 'Enable Paragraph Blocks' checked in the field configuration, verify the max_cardinality setting is high enough, and confirm the entity type has Layout Builder enabled.
Keep 'Display individual paragraph blocks in the UI' disabled (default) and use a reasonable max_cardinality value. The module automatically filters to show only relevant blocks.
The module should automatically update block configuration on save. If issues persist, check that hook_entity_presave is firing correctly and the entity isn't being synced (Workspaces).
Ensure the Token module is installed and enabled. Token patterns are only processed when Token is available.
This is expected behavior - admin title is automatically hidden for nested paragraphs since only top-level paragraphs are used as blocks.
Security Notes 2
- The module requires 'administer paragraphs settings' permission for accessing configuration
- No additional security concerns beyond standard Drupal field and entity access controls