Paragraphs Bundles

Paragraphs Bundles provides reusable Drupal Paragraphs components for layouts, media, interactive displays, and content integrations. The companion PB Import module supports CSV-based imports.

The module provides 31 selectable paragraph components with configurable colors, borders, spacing, widths, layouts, and responsive behavior. Interactive components use vanilla JavaScript rather than jQuery, and optional Solo theme integration adds theme-specific page controls.

Version 2.0 supports Drupal 11.3 and Drupal 12, adds the Paragraphs List administration page, and writes editor styling to generated stylesheets instead of inline styles. Sites on 1.x should read the Upgrading from 1.x section below before updating; the upgrade is one-way.

Watch the Paragraphs Bundles playlist - Explore a live demonstration

Some Paragraphs Bundles display patterns are also available as Drupal Views styles in the Vanilla Views suite. The ten modules use vanilla JavaScript and provide Accordion, Basic Carousel, 3D Carousel, 3D FlipBox, Hero, Lightbox, Parallax, Reveal, Slideshow, and Tabs.

Landing-page examples built with Paragraphs Bundles and the Solo theme

Blue Skyline - Bright Den - Calm Corner - Color Whirl - Dawn View - Dream Road - Dusk Deck - Earth Base - Green Park - Jewel Place - Ocean Field - Peace Beach - Red Hill - Ring Retreat - Secret Garden - Shadow Line - Shine Land - Sky Pattern - Space Art - Star Circle - Star Gate - Star Home - Summit Point - Sun Plains

Solo theme color schemes used by the demonstrations

The Solo theme used by the demonstration site includes 50 predefined color schemes:

Berry Blue Dreams - Blueberry Skies Quartet - Blushing Magnolia - Celestial Blue Depths - Charcoal Gray - Classic Ivory Lace - Cotton Candy Whispers - Crimson Denim Night - Deep Ocean Shadows - Deep Sea Echo - Denim Twilight - Dusk Shadow Fusion - Eclipse Noir - Enchanted Forest Zest - Ethereal White Harmony - Flaming Sapphire - Galactic Stone Hues - Gentle Ivory Breeze - Gunmetal Echo - Indigo Pulse - Ivory Whisper - Jungle Denim Fusion - Lemon Lime Forest - Luminous Alabaster - Magnolia Afternoon - Metallic Nebula - Midnight Denim Swirl - Midnight Garden Trio - Midnight Navy Duo - Midnight Whispers - Monochrome Splash - Mystic Ash Twilight - Nightfall in Paris - Nocturnal Velvet - Obsidian Cascade - Ocean Depths Mystery - Parisian Skyline - Porcelain Brilliance - Porpoise Dream - Pristine Porcelain Glow - Raspberry Nightfall - Razzle Onyx Elegance - Royal Azure Flame - Rustic Redwood Charm - Salmon Denim Fade - Silken Shadow Whisper - Smokey Quartz Symphony - Soft Silk Elegance - Twilight Ash Mystique - Urban Stone Shadows

New in Paragraphs Bundles 2.0

Version 2.0 is a rewrite of the module's internals for Drupal 11.3 and Drupal 12. Existing paragraph content, field machine names, and stored display values are kept as they are; the changes are in CSS class names, outer element IDs, and how editor styling reaches the page.

Paragraphs List

The Paragraphs List administration page has moved into Paragraphs Bundles from PB Import, at the same address (/admin/content/paragraphs/paragraphs-list) under Content. PB Import 2.x no longer provides it.

• Sort, search by content title or label, show or hide columns, and page through results with bookmarkable Previous and Next links.
• Access requires the restricted Access the Paragraphs List permission, because the list includes unpublished paragraphs. Editing and deleting also require update access to the host content.
• An index table and keyset paging keep the list usable on sites with very large numbers of paragraphs. Drush commands rebuild and verify the index.

Optional sub-modules

• paragraphs_bundles_ai: an AI assistant that writes a section on the page from one sentence. See AI assistant below.
• paragraphs_bundles_apex: sizes each media image for the box it lands in rather than for the screen. See APEX responsive images below.

Components and editing

• 3D Carousel coverflow: a new Carousel style field offers Rotating ring (the default, used by existing carousels) or Coverflow.
• Alert state: alerts can be marked Success, Info, Warning, or Error, each with an icon and a default color.
• CSS Classes field: all 31 components accept extra CSS classes in a collapsed Advanced group on the Display tab.
• Link colors: Link Color and Link Color Hover fields join the shared Display tab colors.

Performance, security, and accessibility

• Icon-font subsetting: the Icon component requests a Google Fonts subset containing only the Material Symbols icons a site uses. The full fonts still ship with the module and are used when Google Fonts cannot be reached or a site uses a very large number of icons.
• Strict CSP ready: editor colors and spacing are written to generated, cacheable per-paragraph stylesheets, so pages work under a Content Security Policy that forbids inline styles. Pages with Material Symbols icons also need fonts.googleapis.com and fonts.gstatic.com allowed.
• Validated editor values: color values are validated when saved, including through REST and JSON:API, and validated again wherever CSS is written; invalid values produce no output.
• Accessibility fixes: the slideshow no longer takes over the Space key and has a pause control, the alert no longer dismisses itself on a timer, animations respect reduced-motion preferences, the carousel has an accessible name, and the 3D Flip Box can be operated by keyboard.
• No jQuery on the front end: the Tabs, Carousel, 3D Carousel, Modal, Accordion, and Icon libraries no longer load jQuery.

The complete list of changes is in the Paragraphs Bundles 2.0.0 release notes.

AI assistant: build a section by saying what it should say

The optional paragraphs_bundles_ai sub-module puts an assistant on the pages your editors already edit. Instead of opening a form and filling one field after another, an editor picks a section, describes it in a sentence such as "our autumn range, warm and short", and the section is built on the page: written, filled with what goes inside it, and ready to review. Paragraphs Bundles works exactly as before without it.

What an editor sees

• A bar at the foot of the page. On a page the editor may edit, the assistant bar appears at the bottom. A small half-circle button on its top edge hides it and brings it back, and the browser remembers the choice.
• Sections grouped by what you are building. The Add section list is grouped into Banners; Images, icons and links; Interactive sections; Layout and structure; Reveal; and Text. With every component installed it offers 26 sections. Slides, tab panels, and card panels are not in the list, because they are written inside the section they belong to.
• A box that tells you what to say. Choosing a section rewrites the hint inside What should it say?, built from that section's real fields. For a Hero it reads: Heading "…" as an h2, centred, then the Body and the Image Link Title. One sentence sets the heading text, its level, and its alignment together.
• A brief for every section. The Prompts and Best practices switches open a panel saying what the section is good for, how to get the best from it, and which fields it needs, each marked Content or Display so you know which tab to open. Example prompts are shown one at a time, so the panel fits without scrolling.
• Simple controls for the rest. How many sets the number of slides, rows, tabs, or carousel items. Style picks a look. Where appears only when the content type has more than one paragraph field.

What it does for you

• Fills what goes inside a section, not only its heading. Slides, rows, tabs, and carousel items are created and nested; sections with several places, such as columns or a flip box's two faces, get one in each. It builds one level of inner sections, and refuses a deeper request rather than guessing.
• Supplies pictures sized for the slot. A model can write a hero's words but cannot choose its picture, so each required picture field gets a gray placeholder drawn at the size that slot crops to, with the numbers on it (for example, 1700 x 600 for a hero and 900 x 540 for a card image), and the note names each field to replace. The placeholder is added to the media library once and reused.
• Switches features on and names them. A new section arrives with its features on, such as a slideshow's arrows, dots, and timing, and the page then lists what was switched on and that each can be changed or turned off in the section's Display tab.
• Applies named looks. Four styles ship: Warm, Calm, Dark, and High contrast. They are written by a person, every color pair in the shipped four meets WCAG AA contrast, and a site can edit them or add its own.
• Marks what still needs you. When a section needs something only a person can choose, a notice beside the list names those fields before you add it.
• Changes one section you point at. Hover a section to see its id, choose it in Or edit a section, say what should change, and press Edit that section. Only that section's words change.
• Shows its work. The page reloads onto the new section, marks it New, and offers an Undo link to editors who are allowed to revert revisions.

What it will not do

• It never publishes. A new page is created unpublished, and a change to an existing page is saved as a new revision.
• It never touches a section you did not point at, never another page, and never changes a section's type.
• It never chooses a color or a picture. The model is asked only for words, inside a shape built from that section's own fields and allowed values.
• It never acts beyond your permissions. It needs the Use the Paragraphs Bundles assistant permission, and every save re-checks that you may edit the page.

AI assistant requirements

• The AI module and an AI provider module with a key configured. The sub-module never asks for, stores, or sends a key itself. AI Assistant API, AI Agents, and AI Chatbot are not needed.
• Drupal 11.3 or later on Drupal 11: the sub-module declares ^11.3. Drupal 12 support follows the AI module, and Paragraphs Bundles itself already supports Drupal 12.

After enabling it, choose a default chat provider and model under Configuration, AI, Settings, and grant the assistant permission to the roles that should use it. The sub-module ships a worked example prompt for every section type, each one actually run, in AI-PROMPTS.md.

APEX responsive images: size each picture for the box it lands in

The optional paragraphs_bundles_apex sub-module lets Paragraphs Bundles media images use APEX's layout-aware responsive image formatter. Instead of choosing an image file from the width of the screen, it chooses one from the width of the slot the image is actually shown in.

The problem it solves

Without it, Paragraphs Bundles picks an image by viewport: the wide responsive image maps six screen widths to six fixed image styles. That is right only when the image fills the screen. A 300px image in a sidebar on a 1920px monitor still gets a 1920px-class file.

APEX computes the actual slot width (site width minus padding, minus container gaps, times the slot's share of the grid) and writes it into the image's sizes attribute. The attribute leads with auto, so browsers that support it measure the rendered box exactly, and the computed value is the fallback for those that do not. APEX's own measurement on a real site: 16 images spanning 290px to 1393px all carried one identical sizes value, 12 downloaded the wrong image derivative, and 2060 KB was fetched where 1238 KB was correct.

What it installs

• PB Media APEX Wide (16:9), pb_apex_wide, using APEX's hero mode.
• PB Media APEX Narrow (4:3), pb_apex_narrow, using APEX's content mode.
• PB Media APEX Card (3:2), pb_apex_card, using APEX's card mode.

These are three media view modes on the Image (PB) media type. The sub-module ships no image styles of its own, because APEX owns them, and it does not need core's Responsive Image module.

How to use it

Enabling the sub-module changes nothing on its own; it only adds the three view modes to a select list. To switch a component, open its paragraph type's Manage display page and set the image field to the matching mode:

• Hero, Image Wide, and Image Overlay: PB Media APEX Wide.
• Image Narrow: PB Media APEX Narrow.
• Card Image Section: PB Media APEX Card.

To go back, select the original Paragraphs Bundles view mode again; the sub-module never edits Paragraphs Bundles' own view modes. Do not switch Parallax Section: it draws its picture as a CSS background, and the APEX formatter would break it. If an administrator deletes an APEX mode that a display uses, the status report names the display and the missing mode.

drush en paragraphs_bundles_apex -y
drush cr

Two differences to know before switching

1. The crop shape changes. APEX's modes keep one strict ratio at every breakpoint. Paragraphs Bundles' wide styles do not; their ratios run from 1.50 to 3.37 across the six. Switching a hero is a visible design change, not only a file-size one.
2. You lose the loading control, but not the default. Paragraphs Bundles' displays ship lazy loading and let a site builder switch one to eager on Manage display. The APEX formatter has no loading setting: it always outputs lazy loading and leaves promoting the main (LCP) image to APEX's performance module.

Source images should be at least 1920px wide; APEX's extra-large hero style is 1920px and enlarges anything narrower.

APEX responsive images requirements

• APEX (drupal/apex), whose apex_responsive_image module this sub-module depends on.
• Paragraphs Bundles' Image component (paragraph_bundle_image) and core Media.
• Drupal ^11.3 || ^12.

Paragraphs Bundles live examples

1. Paragraph Bundle 3D Carousel Example
2. Paragraph Bundle Carousel Example
3. Paragraph Bundle 3D Flip Box Example
4. Paragraph Bundle Accordion Example
5. Paragraph Bundle Alert Example
6. Paragraph Bundle Block Content Example
7. Paragraph Bundle Card Three Columns Example
8. Paragraph Bundle Card Two Columns Example
9. Paragraph Bundle Contact Form Example
10. Paragraph Bundle Drupal Block Example
11. Paragraph Bundle Grid Example
12. Paragraph Bundle Hero Example
13. Paragraph Bundle Icon Example (Google Material Symbols & Image)
14. Paragraph Bundle Image (Original Size) Example
15. Paragraph Bundle Image Background Example
16. Paragraph Bundle Image Overlay Example
17. Paragraph Bundle Lightbox Image Grid Example
18. Paragraph Bundle Link Example
19. Paragraph Bundle Modal Example
20. Paragraph Bundle Node Reference Example
21. Paragraph Bundle One Column Example
22. Paragraph Bundle Parallax Example
23. Paragraph Bundle Responsive Image Narrow Example
24. Paragraph Bundle Responsive Image Wide Example
25. Paragraph Bundle Simple Example
26. Paragraph Bundle Slideshow Example
27. Paragraph Bundle Tabs Example
28. Paragraph Bundle Three Columns Example
29. Paragraph Bundle Two Columns Example
30. Paragraph Bundle Views Example
31. Paragraph Bundle Webform Example
32. PB Content & PB Block Types Example - Understanding the PB Paragraphs Content Type and PB Block Type

Features

• jQuery-free interactions: Interactive components use vanilla JavaScript and Drupal core libraries.
• Configurable presentation: Components provide controls for colors, borders, spacing, widths, layouts, shadows, and background opacity.
• Five responsive breakpoints: Multi-column components can change their layouts at five configurable viewport thresholds.
• Organized editing: Content and Display tabs separate editorial fields from presentation controls.
• Optional Solo integration: Theme-specific controls are available when the Solo theme is used.

Each component is packaged as an optional submodule so site builders can enable only what a site needs. This keeps the Paragraphs add dialog, active configuration, dependencies, and front-end assets focused instead of loading every available bundle.

The module allows the creation of paragraph bundles that consist of two group field horizontal tabs: Content and Display.

Display tab

The Display tab provides a comprehensive set of customization options for the appearance of the paragraph bundle. It includes eight color input fields for:

• Background color
• Background color hover
• Text color
• Text color hover
• Link color
• Link color hover
• Border color
• Border color hover

In addition to these, there are seven more fields for further customization:

• Border
• Border radius
• Margin
• Padding
• Max Width
• Box shadow
• Background color opacity

These 15 fields are the default and are found in most bundles, grouped into Colors, Border & radius, Spacing, and Size & effects sections. A collapsed Advanced group holds the CSS Classes field. However, the number of fields can vary according to the bundle type.

Content tab

The Content tab is where the actual content fields of the bundle are located. The number of fields here will depend on the bundle type.

Where a component provides a title, editors can select H1 through H6 or a plain container and align the title left, center, or right. Editors should choose a level that preserves the page heading hierarchy.

Return to the project overview

31 paragraph components and page-building tools

The module provides 31 selectable paragraph components, plus the PB Block custom block type, PB Content content type, and PB Node Reference content type.

The paragraph components are organized into four groups: Display Formats, Interactive Elements, Layout Structures, and Content Integration.

1. Display formats

1. 3D Carousel: Presents content in a rotating 3D ring or a coverflow of angled cards.
2. Carousel: Displays nested content with configurable navigation, looping, autoplay, spacing, and slide width.
3. 3D Flip Box: Displays content in boxes that flip in a 3D space.
4. Lightbox Gallery: Arranges images in a responsive grid layout and opens each image in a Lightbox.
5. Slideshow: Shows content in a slideshow format.
6. Responsive Image Narrow: Adapts images to fit different screen sizes, either in square formats.
7. Responsive Image Wide: Adapts images to fit different screen sizes, either in rectangle formats.
8. Parallax: Creates a parallax scrolling effect for images or other content.

2. Interactive elements

1. Accordion: Displays content in a collapsible format, allowing users to expand or hide sections.
2. Tabs: Organizes content in a tabbed interface.
3. Modal: Displays content in a modal window, often used for login forms, notifications, or additional information.
4. Alert: Shows alert messages or important information, with a Success, Info, Warning, or Error state.

3. Layout structures

1. Grid: Displays content in a grid layout, adjustable between one and twelve columns.
2. One Column: A simple, single-column layout.
3. Two Columns: Divides content into two responsive columns with optional sticky and collapsible behavior.
4. Three Columns: Arranges content in three responsive columns with optional sticky and collapsible behavior.
5. Card Two Columns: Displays content in a card-style layout within two columns.
6. Card Three Columns: Displays content in a card-style layout within three columns.
7. Hero: Typically a large, full-width banner or image, often used at the top of a page.

Return to the project overview

4. Content integration

1. Node Reference: For referencing any content.
2. Block Content: For placing and arranging blocks of content.
3. Drupal Block: Integrates Drupal blocks into the layout.
4. Image: A module dedicated to displaying individual images.
5. Image Overlay: Adds overlay effects to images.
6. Link: Specifically for adding and managing hyperlinks.
7. Image Background: Create any content with an image background.
8. Simple: Provides a general-purpose content component.
9. Icon: Display Google Material Symbols or Image Icon.
10. Views: Integrates the Views module, a powerful Drupal tool for organizing and displaying content.
11. Contact Form: Embeds contact forms.
12. Webform: Embeds web forms for user input and interaction.

Each component can be configured through its Content and Display tabs.

The PB Block is a custom block that includes a paragraph field. This block can be utilized whenever you need to create a paragraph block and reference it in any content type or position it in any region. It is compatible with all themes.

PB Content is a custom content type with its own width and background settings. It can be used with any theme; its region controls are designed for the Solo theme. Its form is organized into Content and Display tabs.

Display tab

• A list of all solo regions that can be disabled.
• A field to select the maximum content width (800px / 50rem, 1024px / 64rem, 1280px / 80rem, 1440px / 90rem, 1600px / 100rem, 1920px / 120rem, 2560px / 160rem or 100%).
• An input field to select the content background color.
• A slide range field to select the background opacity value from (1 to 100).

Content tab

• A paragraph field to add any paragraph bundle. Note that the width setting for the paragraph bundle is disabled; the content settings will override it.
• A block content reference field. Here, you can reference any paragraph block field created by PB Block.

PB Content can create a page with an independent width and background and can suppress selected Solo regions such as the header, menus, and footer. Combined with the column components, it supports standalone landing-page layouts.

Requirements

• Drupal ^11.3 || ^12
• PHP 8.3 or later
• Paragraphs ^1.18
• Entity Reference Revisions ^1.10
• Field Group ^3.4 || ^4

On Drupal 12, Composer can install Paragraphs Bundles only once a Drupal 12-compatible release of Paragraphs is available.

Some components need an additional module: Contact Form needs drupal/contact_formatter, Link needs drupal/link_attributes, Views needs drupal/viewsreference, and Webform needs drupal/webform. The optional paragraphs_bundles_ai sub-module needs drupal/ai, and paragraphs_bundles_apex needs drupal/apex.

Installation

composer require 'drupal/paragraphs_bundles:^2.0'

Composer installs Paragraphs, Entity Reference Revisions, and Field Group. Enable Paragraphs Bundles, then enable the component sub-modules a site needs from the Paragraphs Bundles package on the Extend page.

Upgrading from 1.x

The upgrade from 1.x to 2.0 is one-way; there is no downgrade path, and a backup is the only way back.

1. Update to the latest 1.x release and run its database updates first. Version 2.0 refuses to update a site whose Paragraphs Bundles schema is below 9004 and reports that an intermediate version is required.
2. Back up the database and files.
3. Update any theme CSS or JavaScript that targets Paragraphs Bundles classes or IDs. Structural classes now follow a BEM naming pattern (for example, pb__accor-wrap becomes pb-accordion), and outer element IDs now use #pb-{bundle-slug}-{id} (for example, #pb__nf-42 becomes #pb-node-reference-42). Nothing warns at runtime when an old selector stops matching.
4. Install 2.0 and run the database updates, then rebuild caches:

composer require 'drupal/paragraphs_bundles:^2.0'
drush updb
drush cr

Paragraph content is not migrated: field machine names, stored values, and CSS custom properties such as --pb-bg are unchanged. The database updates add the new shared fields, reorganize the Display tab, and regenerate each paragraph's stylesheet.

Read the Paragraphs Bundles 1.x to 2.0 upgrade guide before upgrading. It covers maintenance mode, backups, expected warnings, and recovery. The full class and ID map is in docs/CSS-CLASS-MIGRATION.md in the module.

Usage

After enabling the module, you can start creating custom paragraph bundles. Each bundle can be customized with its own colors, border, layout, box shadow, margin, and padding.

Support and maintenance

Questions, ideas, and bug reports are welcome. Please use this project’s issue queue so discussions and solutions remain available to the Drupal community.

Maintainers monitor issues, but response times depend on availability.

Developed and maintained by Alaa Haddad of Flash Web Center, LLC.

AI disclosure: AI tools assisted with drafting and reviewing this project description. The maintainer verified the final content against the project source.