Paragraph Blocks
paragraph_blocks
Enables placing individual paragraph field values as separate blocks in Layout Builder.
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.
Install
composer require 'drupal/paragraph_blocks:^4.1'
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
Dependencies
Related Projects
Primary integration target. Paragraph Blocks provides block plugins that can be placed in Layout Builder layouts, both for per-entity-type defaults and per-entity overrides.
Supports content moderation workflows by loading the latest entity revision when displaying paragraph blocks, ensuring draft content is properly previewed.
Supports paragraphs from the library by resolving the actual paragraph content from library items when determining block labels and rendering.
When Token module is enabled, admin titles can use token patterns like [paragraph:field_text] for dynamic title generation. Token browser is shown on paragraph type forms.
Integrates with layout builder restrictions by grouping paragraph block options and simplifying the UI when many blocks are available.
Respects workspace syncing operations to prevent paragraph ordering issues when publishing from workspaces.
Admin Pages
| Title | Path | Description |
|---|---|---|
| Paragraph Blocks settings | /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
| Hook | Description |
|---|---|
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
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
- The module requires 'administer paragraphs settings' permission for accessing configuration
- No additional security concerns beyond standard Drupal field and entity access controls