Component-Based Design in Drupal: SDC, UI Patterns, and the Future of Theming

Component-Based Design in Drupal: SDC, UI Patterns, and the Future of Theming

Sam Rollin
Sam Rollin
August 21, 2025
Last updated : February 15, 2026
August 21, 2025

Building Drupal themes has changed dramatically over the past few years. Instead of creating monolithic templates that handle entire pages, developers now build with components: small, reusable pieces of user interface that you can mix and match like building blocks. This shift isn't just about following trends; it's about creating websites that are easier to maintain, faster to update, and simpler for teams to work on together.

If you're managing a Drupal project or planning a redesign, understanding component-based design will help you make better decisions about your site's architecture. This approach affects everything from how quickly you can roll out new features to how consistently your brand appears across different pages.

Core Concept Explanation: Understanding Components in Drupal

Think of components as self-contained units of your website's interface. A component might be a card that displays content, a hero banner at the top of a page, or even something as simple as a button. Each component includes everything it needs to function: its HTML structure, CSS styles, JavaScript behavior, and the data it expects to receive.

In Drupal, two main tools bring component-based design to life: Single Directory Components (SDC) and the UI Patterns module. SDC became part of Drupal core starting with version 10.1, marking a significant shift in how Drupal approaches theming. UI Patterns, a contributed module, extends these capabilities by making components available throughout Drupal's administrative interface.

Here's what makes a component different from traditional Drupal templates:

Traditional approach: You might have a node template that handles an entire article display, mixing concerns about layout, styling, and content structure all in one file.

Component approach: You create a "card" component that knows how to display any piece of content in card format. This same card works whether you're showing an article teaser, a team member bio, or a product listing.

Components follow a simple structure. Let's look at a basic card component:

mytheme/
  components/
    card/
      card.twig          # The HTML template
      card.component.yml # Component metadata
      card.css          # Styles for this component
      card.js           # Any JavaScript needed

The .component.yml file defines what data the component expects:

label: 'Card'
props:
  type: object
  properties:
    title:
      type: string
      description: The card title
    body:
      type: string
      description: Main content text
    image_url:
      type: string
      description: URL for the card image

This structure keeps everything related to the card in one place. When you need to update how cards look across your entire site, you change files in one directory instead of hunting through multiple template files.

Comparisons and Options: SDC vs UI Patterns vs Traditional Theming

When planning a Drupal project, you have three main approaches for theming. Each serves different needs and project requirements.

Single Directory Components (SDC) represents Drupal's native approach to component-based design. Since it's part of core, you don't need additional modules to start using it. SDC excels at organizing your theme files and automatically loads CSS and JavaScript only when components appear on a page. This reduces page weight and improves performance.

SDC works best when:

  • Starting a new Drupal project from scratch
  • Your development team knows Twig and component patterns
  • You want to stay close to Drupal core functionality
  • Performance and clean code organization are priorities

UI Patterns module builds on top of SDC (in version 2.x) and adds powerful features for content editors and site builders. It exposes your components as blocks, layouts, and field formatters that non-developers can use through Drupal's admin interface. This means a content editor can place a "card" component on a page and fill in its content without touching code.

UI Patterns fits projects where:

  • Content editors need flexibility to build varied layouts
  • You're retrofitting an existing site with components
  • Integration with Layout Builder is important
  • You want to provide a library of pre-built design patterns

Traditional theming still has its place, particularly for simple sites or when maintaining legacy projects. With this approach, you create separate template files for different content types and use Drupal's theme suggestions system to control display.

Consider traditional theming when:

  • Working with a very simple site structure
  • Maintaining an existing site that would be expensive to refactor
  • Your team lacks experience with component-based development
  • Quick delivery matters more than long-term maintainability

Here's a practical comparison:

| Aspect | SDC | UI Patterns | Traditional |
|--------|-----|-------------|-------------|
| Learning curve | Moderate | Steeper | Gentle |
| File organization | Excellent | Good | Can get messy |
| Editor experience | Developer-focused | Editor-friendly | Limited flexibility |
| Performance | Excellent | Good | Variable |
| Maintenance effort | Low | Low to moderate | High for complex sites |
| Setup time | Moderate | Higher | Quick |

Use Cases and Applications

Let's explore how component-based design works in real scenarios.

Marketing team needs: A marketing manager wants to create landing pages with different layouts for various campaigns. With UI Patterns integrated into Layout Builder, they can drag and drop pre-built components like testimonial cards, feature lists, and call-to-action blocks. Each component maintains brand consistency while allowing content customization.

Multi-site deployments: A university running 50 department websites needs consistent design elements while allowing some customization. Components let you share a library of approved patterns across all sites. We've found that teams save weeks of development time by reusing components across similar projects instead of rebuilding functionality for each site.

Design system implementation: Your company has invested in a design system with detailed specifications for buttons, forms, cards, and other UI elements. SDC maps perfectly to this structure. Each design system component becomes an SDC component in Drupal. Designers can update the design system, and developers can update the corresponding components without affecting the rest of the site.

Progressive enhancement: You're building a media-rich site that needs to work well on slow connections. Components let you implement progressive enhancement patterns easily. A video card component might show a static image by default, then load its JavaScript to add playback controls only when needed. The component encapsulates both the basic and improved versions.

Content migration projects: When migrating from another CMS, components help you maintain visual consistency while changing the underlying content structure. Create components that match your current design, then map your migrated content to fill those components. This separation between presentation and content makes migrations smoother.

Decision Framework: Choosing Your Approach

Making the right choice for your project requires evaluating several factors. Here's a framework to guide your decision.

Assess your project timeline. New projects starting from scratch should strongly consider SDC as the foundation. You'll build better habits from the beginning and avoid technical debt. Existing projects need more careful evaluation. The benefits of components might not justify a complete refactor if your current templates work well.

Evaluate your team's skills. Component-based development requires thinking differently about templates. Developers need to understand props, slots, and component composition. If your team has React, Vue, or similar experience, they'll adapt quickly. Working with teams has taught us that developers without component experience typically need 2-3 weeks to become productive with SDC.

Consider your content editors. How much control do content editors need over page layouts? If they frequently create unique page designs, UI Patterns with Layout Builder provides the flexibility they need. If most pages follow standard templates, SDC alone might suffice.

Think about long-term maintenance. Components require upfront investment but pay dividends over time. Sites that change frequently or have multiple developers benefit most from component organization. Small sites with static content might not see enough benefit to justify the initial setup.

Review your integration needs. Planning to use Storybook for component documentation? Need to share components with a React application? SDC provides better integration points for these scenarios. Traditional theming makes these integrations much harder.

Budget for training and documentation. Moving to components means documenting your component library and training your team. Factor in time for creating component guidelines, usage examples, and onboarding materials.

Professional Recommendations

After implementing component-based designs across dozens of Drupal projects, some clear patterns emerge about what works.

Start small with high-value components. Don't try to componentize everything at once. Begin with elements you use frequently: buttons, cards, heroes, and basic layouts. Build your component library gradually as you identify reusable patterns. Our experience shows that starting with 5-10 core components covers 60-70% of typical page layouts.

Establish naming conventions early. Consistent component naming prevents confusion as your library grows. Use clear, descriptive names that describe what the component is, not where it's used. Name it "card," not "homepage-card," since you'll likely use it elsewhere.

Document as you build. Every component needs basic documentation: what props it accepts, when to use it, and at least one example. The SDC example.yml files provide a perfect place for this. Good documentation saves hours of developer time and prevents misuse of components.

Create a component playground. Set up Storybook or use the SDC Styleguide module to create a browsable component library. This helps designers verify implementations, developers understand available options, and stakeholders see progress.

Plan for component evolution. Components will need updates as requirements change. Design your components to accept optional props for variations rather than creating numerous similar components. A single card component with style variants beats having basic-card, fancy-card, and simple-card components.

Test across contexts. Components should work correctly whether they're placed in a sidebar, main content area, or Layout Builder section. Test your components in different regions and with various content lengths to catch issues early.

Consider performance from the start. SDC's automatic asset loading helps, but you still need to think about performance. Keep component CSS focused and avoid loading heavy JavaScript libraries unless necessary. Use Drupal's lazy loading capabilities for images within components.

Conclusion: Making Component-Based Design Work for You

Component-based design represents a fundamental shift in how we build Drupal themes. By breaking interfaces into reusable pieces, this approach delivers cleaner code, better performance, and easier maintenance. SDC brings these benefits directly into Drupal core, while UI Patterns extends them to content editors and site builders.

The choice between SDC, UI Patterns, or traditional theming depends on your specific needs. New projects should strongly consider starting with SDC. Existing sites might benefit from gradually introducing components through UI Patterns. Even traditional theming still serves a purpose for simple sites or when rapid delivery outweighs other concerns.

Success with components requires planning, consistent naming, good documentation, and team training. The initial investment pays off through faster development, fewer bugs, and happier content editors who can build pages without developer assistance.

If you're evaluating component-based design for your Drupal project, we can help you assess which approach fits your team's workflow and technical requirements. Whether you're starting fresh with SDC, need to integrate UI Patterns with your existing Layout Builder setup, or want to create a shared component library across multiple sites, we'll work with you to build a theming architecture that grows with your needs.

Share this article