Building Reusable Component-Based Content Architectures in Umbraco

Modern web development has moved well past the era of page-by-page content management. Today, the teams building at scale whether across microsites, multilingual portals, or enterprise platforms need their CMS to think in systems, not pages. Umbraco, with its flexible document type structure and developer-first philosophy, is exceptionally well-suited for this shift.

Component-based content architecture is the approach of breaking down a website into discrete, reusable content blocks each independently managed, independently styled, and independently deployable. When done right in Umbraco, it dramatically reduces content duplication, speeds up editorial workflows, and makes your front-end codebase significantly easier to maintain.

This post walks through the core patterns developers should know when building reusable component architectures in Umbraco from document type design to rendering strategies.

1. Design Your Document Types Around Components, Not Pages

The most common mistake in Umbraco projects is building document types that mirror page layouts. Instead, think in terms of content atoms individual units of structured content that can live anywhere.

Use case: A "Testimonial" block that appears on the homepage, a product page, and a case study page should be one document type, not three variations of the same fields scattered across different page types.

How to implement it:

• Create element types (in Umbraco 10+, these are non-node document types used purely for composition)
• Define your reusable blocks Hero, Card, Stat Block, CTA, Quote as standalone element types
• Use Block List Editor or Block Grid Editor to compose page layouts from these blocks

Benefits:

• One source of truth for each content pattern
• Editors can reuse blocks across page types without developer involvement
• Structural changes propagate everywhere the block is used

2. Use Block Grid for Layout-Aware Component Systems

The Block Grid Editor from Umbraco (available from version 10) is the most effective solution for creating component-based architectures. It enables programmers to create a grid structure and then match elements within it, thus providing editors with some degree of freedom.

Use case: A team of marketers creates campaign landing pages with the need for some flexibility in organizing blocks of content.

How to implement it:

• Define allowed block types per grid area
• Set column span rules per block (e.g., a Hero always spans 12 columns, a Card spans 4)
• Pair block configurations with corresponding Razor partial views or front-end components

Benefits:

• Enforces design constraints while enabling layout flexibility
• Reduces bespoke page templates one grid template handles dozens of page layouts
• Cleaner separation between content structure and visual presentation

3. Centralise Shared Content With Umbraco's Content Picker and IPublishedContent

Some content isn't just reusable, it's shared. Author bios, product specifications, office locations, and legal disclaimers need to exist once and be referenced everywhere, not copied.

Use case: A global footer that pulls live from a single "Footer Settings" node, updated once and reflected sitewide.

How to implement it:

• Store shared content in dedicated content nodes (e.g., under a "Site Settings" section)
• Use Content Picker properties to reference these nodes from any page or block
• Query via IPublishedContent or strongly-typed models using Umbraco's ModelsBuilder

var footer = _contentQuery.ContentSingleAtXPath("//siteSettings/footer");

Benefits:

• Single-edit, everywhere-updated content
• No risk of stale or out-of-sync duplicates
• Works well with multilingual setups using Umbraco's language variants

4. Abstract Rendering With Partial Views and View Components

A reusable content model is only half the equation. Your rendering layer needs to match otherwise, the same block type ends up with ten different Razor implementations scattered across your project.

Use case: A "Card" element type used in a blog listing, a team page, and a product overview should render from a single partial, not three separate files.

How to implement it:

• Map each element/block type to a dedicated partial view under /Views/Partials/Blocks/
• Use @Html.Partial() or ASP.NET Core View Components for more complex blocks with their own logic
• Pass strongly-typed models — avoid ViewData or dynamic casting in partials

@await Component.InvokeAsync("CardBlock", new { model = block.Content.Value<CardBlock>() })

Benefits:

• Consistent rendering output across all usage contexts
• Easier to test, extend, and hand off to front-end developers
• Changes to a block's rendering propagate automatically

5. Version and Govern Your Component Library

The component-based architecture introduces another problem, that of governance. As you start increasing your collection of blocks, there is every possibility of creating duplicate types, naming inconsistencies, and even deprecation of some blocks that are never removed.

Use case: The development team starting a new project should be aware of the approved blocks, deprecated blocks, and composition policies.

How to implement it:

• Maintain a component manifest a simple internal doc (or Storybook instance) mapping each block to its document type, allowed contexts, and rendering view
• Use Umbraco's backoffice descriptions and icons to differentiate block types visually
• Periodically audit document types and remove unused element types via Umbraco's content type clean-up tools

Benefits:

• Reduces sprawl as the project scales
• New developers can onboard faster with a clear component map
• Editorial teams gain confidence in what's available and when to use it

Best Practices

• Start with a block inventory before building. List every recurring content pattern on the site before creating a single document type. Group similar patterns and eliminate redundancies early.
• Name document types semantically, not visually. Call it TestimonialBlock, not GreyBoxWithQuote. Visual treatments change; content purpose doesn't.
• Avoid deep nesting in Block List. More than two levels of nested blocks becomes an editorial nightmare. Prefer flat structures with rich configuration options per block.
• Use ModelsBuilder in pure mode. Strongly-typed models eliminate magic string bugs and make your component code significantly easier to refactor.
• Test blocks in isolation. Each partial view should render correctly with mock data before being integrated into a page template.
• Document deprecations explicitly. When a block is retired, flag it in the backoffice description and remove it from allowed block lists before eventual deletion.

Conclusion

Component-based content architecture in Umbraco isn't just a development pattern it's a long-term investment in the maintainability and scalability of your platform. When your document types, rendering layer, and editorial tooling all speak the same language, the result is a CMS that grows with your project instead of against it.

The patterns covered here from element types and Block Grid to shared content nodes and governed rendering are the building blocks of production-grade Umbraco architecture. The more deliberately you design your component system upfront, the less technical debt your team inherits as the site evolves.

Whether you're working on a mid-market brand site or an enterprise multi-tenant platform, these principles apply. Build for reuse, design for governance, and let Umbraco do what it does best.

Written by

Nishant Vaghasiya

Technical Architect

I'm Nishant Vaghasiya, a Technical Architect and Umbraco & Sitecore Certified Developer at Arroact Technologies. I specialise in building digital solutions with Umbraco and Sitecore that are practical, scalable, and built to last.

Over the years, I've learned that the best solutions aren't always the most complex ones, they're the ones that make a team's day-to-day work simpler and give them confidence that the system won't let them down.

That's what drives me writing code that performs well, stays reliable, and continues to create real impact long after it goes live.