Component-based Drupal — how it is built in practice

Drupal has several ways to build a page from components. Which one fits depends on whether the layout decision belongs to the editor or the developer.

Component-based development means that page content and design are built from reusable blocks — each block is self-contained, tested and usable in multiple places. The opposite approach is page-by-page design: every page has its own layout, there are no shared components, and code is duplicated.

In Drupal, this is an architectural choice made at the start of a project. Changing it later is expensive.

Why it suits Drupal particularly well

Drupal is strongly content-oriented. Content is structured — fields, content types, taxonomy. That structure provides a natural foundation for components: when content is defined as fields, the same content can be displayed in different components without duplication.

The second reason is the role of editors. Drupal is often used by organisations where editors add content themselves — without involving a developer. A component-based system gives editors a bounded set of choices: they can use existing components but cannot break the design. That is the balance between flexibility and control.

Three main approaches in Drupal

Paragraphs

Paragraphs is Drupal's most widely used component solution. An editor builds a page block by block: hero, text with image, quote, call to action. Each block is a separate Paragraph type with its own fields.

Strengths: editors understand immediately how content is structured. There is a clear boundary between components. Developers can control which components are allowed where.

Weaknesses: the hierarchy becomes complex quickly when components are nested inside each other. In large projects, unused Paragraph types accumulate.

Layout Builder

Layout Builder is a Drupal core feature since Drupal 8.5. It gives editors a visual interface for assembling pages — blocks can be dragged, sections added and removed directly on the page.

This works well when different pages need to look different but draw from the same content system. For example, a team page, an event detail page and a campaign page might use the same components in different arrangements.

Strengths: intuitive for editors, does not require a developer for every layout change.

Weaknesses: Layout Builder creates complexity when used without clear rules — editors have too many choices and the result is inconsistent. It needs clear editorial guidelines alongside it.

Single Directory Components (SDC)

SDC is a Drupal 10.1 core feature that changes how themes define components. Each component lives in its own directory — Twig template, CSS, JavaScript and component schema together in one place.

This is primarily a developer tool. Editors do not interact with SDC directly, but developers can build a component library that Paragraphs or Layout Builder uses. The result is a coherent layer: the same component works in code, in a testing environment and on the editor-facing page.

SDC is a newer approach and is gradually replacing the older practice where a component's template, styles and logic lived in separate folders with no clear connection.

Design tokens and the theme layer

In a previous article we wrote about design tokens — how colour, spacing and typography should come from one place rather than being scattered through the code.

In Drupal, this means the theme CSS uses variables (--color-primary, --spacing-md) that components inherit. When the brand colour changes, it changes in one place — not in every component separately.

SDC supports this naturally, since each component can import shared variables. Paragraphs and Layout Builder are independent of the theme layer — the token system is created by the developer, not by a Drupal core feature.

Storybook for component documentation

In a more complex project it is worth documenting the component library separately — for both developers and editors. Storybook is a tool that renders components in the browser without running Drupal.

This brings several benefits:

• developers see a component in isolation, without the context of a full page;
• designers can verify that a component matches the design spec;
• editors get an overview of which blocks are available.

Using Storybook adds work at the start of a project, but reduces confusion later. The question "why does this component look like this here?" is answered in the documentation rather than in a support ticket.

What goes wrong

Common mistakes in component-based Drupal projects:

Too many exceptions. If every page gets its own special rule, components lose their value. Components must be general — a custom solution is the exception, not the rule.

Components without constraints. Editors need a limited set of options. If everything is possible everywhere, the design quickly gets out of control.

Styles inside components instead of in the system. If each component defines its own colours and spacing, there is no system. A change in one place does not reach the others.

Paragraphs nested too deeply. Three levels of nesting is almost always too many. The structure becomes confusing for editors and hard to maintain for developers.

Which approach to choose

There is no universal answer. Questions that help:

• Does the editor need to change the page layout? If yes, Layout Builder. If no, Paragraphs.
• How large is the project? In a smaller project, Paragraphs is simpler and faster to set up. In a larger project, investing in SDC is worthwhile.
• Is a design system in use? If there is a Figma component library, connecting SDC and Storybook is worthwhile — then code and design stay in sync.

Often all three are used together: SDC defines the components, Paragraphs gives editors the input interface and Layout Builder adds flexibility where it is needed.

Examples from WebPro projects

Component-based development has been applied in several WebPro projects at different scales and in different contexts.

Tallinn Health Care College — an institutional platform with over 5,000 pages and around 40 content editors. A component-based frontend allows editors to create consistently designed content without involving a developer.

Palmako associated websites — five international websites on a shared Drupal codebase. The component system enables per-brand customisation while keeping a unified maintenance workflow across all sites.

State Real Estate Ltd — a public sector platform with custom modules, a procurements feature and WCAG 2.1 AA accessibility requirements. A component-based structure makes long-term changes and maintaining WCAG compliance easier.

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.

Contact us