Drupal Paragraphs module — flexible content builder
Paragraphs makes content structured and editor-friendly — but requires thoughtful component design upfront.
Paragraphs is one of Drupal's most widely used contributed modules. It enables building page content as components: a text block, image + text, video block, CTA button, accordion, table — each as a separate component that editors can reorder and configure.
Why Paragraphs instead of a plain text editor?
A plain long text field (WYSIWYG) is flexible but problematic:
- Design depends on what the editor puts in the WYSIWYG
- Styles diverge across different editors
- Layout can break unpredictably on mobile
- Content is hard to restructure later
Paragraphs solves this with structured components: each component is a separate entity with defined fields. Editors cannot accidentally apply the wrong style — component design is defined by the developer.
How Paragraphs works
- The developer defines paragraph types — e.g. "Text block", "Image with text", "Video block"
- Each type has specific fields — heading, body, image, link etc.
- When creating content, the editor chooses which component type to add and fills in the fields
- Design is controlled by Twig templates — the editor cannot break the layout
When Paragraphs fits well
Good fit:
- Content-rich pages where editors need to arrange content flexibly
- Landing pages, public-facing pages, service pages
- When a consistent design system is important across the site
Not a good fit:
- Blog posts or articles that are primarily text
- A simple informational site where all pages share the same structure
- If you are planning headless Drupal — Paragraphs with JSON:API requires extra work
What to plan before development
Component inventory — define all necessary component types before development starts. Adding new types later is straightforward, but the initial architecture affects everything.
Nesting — Paragraphs supports nesting: a paragraph can contain another paragraph. This is powerful but complexity grows quickly. Limit nesting depth.
Editor experience — too many different components confuses editors. Keep the number of component types at a reasonable level (10–20).
Migration — when migrating from an old site, old content needs to be mapped to the paragraphs structure. This requires planning.
Layout Builder vs Paragraphs
Drupal Core includes the Layout Builder module, which is a more visual alternative to Paragraphs. Layout Builder is better for changing page layout; Paragraphs is better for creating structured content.
Many projects use both — Layout Builder for page structure, Paragraphs for content components.
Alternative: Experience Builder
The Drupal CMS project includes a new Experience Builder visual editor, also component-based. It is still in development (2025), but may replace some Paragraphs use cases in the future.
Paragraphs remains the standard solution for the next year or two — a large number of projects use it and the module is well maintained.
If you are considering Paragraphs for a new project, describe your content requirements — we can help design the component architecture.
Kaido Toomingas
WebPro Company OÜ
Need Drupal help?
If the article describes your situation, you do not have to read everything first. A real person will help you choose the next step.