Paragraphs

Paragraphs is a contributed Drupal module that lets editors build a page from stackable, typed pieces instead of one large body field. Each piece is a paragraph: a small entity with its own fields, such as an image with a caption or a pull quote. A paragraph field on a node holds an ordered list of them.

How it works in Drupal 11

Paragraphs depends on Entity Reference Revisions, and release 8.x-1.23 declares Drupal ^10.3 or ^11. A paragraph is an entity with the ID paragraph. Its bundle is a Paragraphs type, a configuration entity with the ID paragraphs_type. Paragraphs are revisionable: the entity class declares its own revision tables.

A site builder creates the types at Structure › Paragraph types (path /admin/structure/paragraphs_type) and adds fields to each, in the same way as for a content type. Then they add a field to a content type, choosing Reference and then Paragraph (revisions), and tick which paragraph types the field allows. The permission administer paragraphs types guards the type list. The optional Paragraphs Type Permissions submodule adds permissions for individual types.

On the edit form, the editor adds paragraphs, picks a type, fills in its fields and drags paragraphs into a new order. The stable widget also offers duplication and a drag and drop mode that can move a paragraph, with its children, into another paragraph. Each type renders with its own template: Paragraphs suggests paragraph--[type].html.twig and a variant per view mode.

Example

A landing page needs a flexible body. Go to Structure › Paragraph types › Add paragraph type and create Text with image, with an image field and a long text field. Create Quote, with a quote and an attribution. Then open Structure › Content types › Landing page › Manage fields, add a Paragraph (revisions) reference field called Sections, and allow those two types. An editor can now stack any mix of text blocks and quotes in any order on each landing page.

Common mistakes

• Trusting old widget names. On 26 October 2026 the project page still describes a Classic widget and an Experimental widget with major changes expected. In 8.x-1.23 the README calls them Legacy (formerly Classic) and Stable (formerly Experimental), and the form display lists Paragraphs Legacy and Paragraphs (stable).
• Expecting shared content. A paragraph belongs to one parent. If several pages need the same block, use the Paragraphs Library submodule or a separate content type.
• Expecting Paragraphs to design the page. A paragraph type defines fields and a display. The arrangement on the page still comes from templates, the type's view modes or another tool.

For marketing and content teams

Paragraphs gives editors a menu of approved building blocks. You add what a page needs, in the order you want, without touching HTML. Ask your developer for the list of paragraph types, and request a new type when a block keeps being faked with formatting in a text field. Because each type has named fields, the content stays structured and can be restyled later. The editor works in a form, not on the finished page. See also Layout Builder for controlling how a page is arranged.

With DXPR

DXPR's comparison with Paragraphs, reviewed on 24 September 2026, says DXPR Builder can be introduced on selected fields or content types while existing Paragraphs pages stay in place. It also says that converting existing content is a separate decision and not an automatic effect of installing DXPR Builder.

Sources

• Drupal.org: Paragraphs project page
• Drupal.org: Paragraphs documentation
• Paragraphs 8.x-1.23: README
• Paragraphs 8.x-1.23: module info file
• Paragraphs 8.x-1.23: Paragraph entity class
• Paragraphs 8.x-1.23: Paragraphs library submodule
• DXPR: DXPR Builder compared with Paragraphs