Umbraco 18 is a different kind of release from versions 14 or 16. It does not rebuild the Backoffice or replace the technological foundations of the CMS. Instead, it introduces one major feature that addresses a familiar problem in real-world projects: reusable content that is not a page and should not have to live in the Content tree.

The answer is Library and Elements.

There are also developer-focused improvements, including typed OpenAPI schemas for the Delivery API, as well as improvements developed throughout the Umbraco 17 release line.

There is one important point to keep in mind: Umbraco 18 is an STS release, while Umbraco 17 remains the current LTS release. Choosing the highest version number is therefore not automatically the best decision for every project.

Library – a new home for reusable content

Many Umbraco projects have a folder somewhere in the Content tree called “Global”, “Shared”, “Settings”, or “Reusable content”.

Inside, you might find:

• global CTAs,
• promotional banners,
• contact information,
• content snippets used in multiple places,
• information shared across several pages.

Technically, this approach works. But it has an important weakness: we are using documents to store something that is not really a page.

Umbraco 18 introduces a dedicated place for this kind of data: the Library.

Library is a new Backoffice section designed for content that should exist independently from the page tree.

The first content type supported by the Library is Elements.

Elements – Element Types become actual content

Element Types have existed in Umbraco for years. Until now, they were primarily used to define the structure of items inside editors such as Block List and Block Grid.

Umbraco 18 expands this model.

An Element Type can now be enabled for use in the Library. Editors can then create actual Elements based on that type and manage them independently from documents.

The model is straightforward:

Element Type → Library → Element → content usage

For example, we can create an Element Type called:

Promotion

with properties such as:

Title
Description
Image
Link

Editors can then create individual promotions directly in the Library.

Importantly, an Element has no URL of its own. It no longer needs to pretend to be a page simply because we need somewhere to store its data.

Element Picker – select instead of copy

The second important part of the new model is the Element Picker.

It allows an existing Element to be selected and used elsewhere in the content.

This may look like a small UI feature, but it represents a significant change in content modelling.

Imagine a message such as:

Free delivery on orders over €75

appearing across a dozen pages.

Without shared content, editors may end up with multiple copies of the same text. Updating the message then means finding every occurrence.

Elements establish the foundation for a different model:

create once → reuse → manage centrally

In Umbraco 18, however, this should still be seen as the first stage of the feature. Full integration of Elements with Block Editors is planned for a later release.

Elements are not “simplified documents”

An important part of the implementation is that Elements are treated as first-class CMS content.

They support familiar content-management capabilities including:

• publishing,
• scheduled publishing,
• rollback,
• permissions,
• auditing,
• validation,
• recycle bin,
• search,
• reference tracking.

This becomes particularly important in larger implementations.

A custom “global content repository” often starts as a few simple records. Over time, questions appear around permissions, change history, publishing, dependencies, and governance.

With Umbraco 18, there are fewer reasons to build this infrastructure from scratch.

Source: CodeMasters – original illustration.

What changes from a developer’s perspective?

The most important change is not another API to learn.

It changes the way we can model content architecture.

Previously, we would often ask:

“Where in the Content tree should this information live?”

With Umbraco 18, it is worth asking a different question first:

“Is this information actually a document?”

If an object:

• has no URL of its own,
• does not require a template,
• should be reusable,
• has its own publishing lifecycle,
• is managed by an editor,

then an Element may be a more natural model than a document.

It is a subtle distinction, but in larger projects it can lead to a much cleaner content structure.

Delivery API – typed OpenAPI schemas

The second major developer-facing change in Umbraco 18 concerns the Delivery API.

Umbraco can generate OpenAPI schemas for individual content types.

This is particularly useful in headless architectures, where the frontend is a separate application consuming CMS content through an API.

Previously, the Delivery API response could appear relatively generic from the perspective of a client generator. Typed schemas provide more precise information about the actual content structure returned by the API.

If we have an:

Article

content type with fields such as:

title
lead
publicationDate

the generated API contract can provide much more accurate information about the returned data.

This provides a better foundation for generating TypeScript, C#, and other API clients.

In practice, this means:

• better autocomplete,
• earlier detection of errors,
• fewer manually maintained DTO models,
• a clearer contract between the CMS and frontend application.

Source: CodeMasters – original illustration.

Moving from Swashbuckle to Microsoft.AspNetCore.OpenApi

Umbraco 18 also changes the technical foundation used for OpenAPI generation.

Swashbuckle is replaced by Microsoft.AspNetCore.OpenApi.

For most standard projects, this will not result in a visible Backoffice change. Custom solutions that modify or extend OpenAPI generation should, however, be reviewed during an upgrade.

This is a good example of the nature of Umbraco 18: some changes are not visible to editors but modernize the technical foundations of the platform and align it more closely with the current ASP.NET Core stack.

Umbraco 18 builds on the Umbraco 17 foundation

Not every improvement available in Umbraco 18 originated directly in version 18.

Umbraco also delivers functionality through minor releases, which means version 18 inherits improvements introduced throughout the 17.x release line.

These include work around performance, caching, the Backoffice, and application operability.

This is important when comparing versions 17 and 18.

Umbraco 18 should not be viewed as a huge collection of features unavailable in 17. Many platform improvements are also delivered to the current LTS release.

The defining feature of version 18 remains Library and Elements.

Migrating from Umbraco 17 to 18

Technically, moving from Umbraco 17 to 18 is much less radical than historical upgrades such as 13 → 14.

The Backoffice, Extension API, Tiptap, and the fundamental platform architecture are already familiar.

Before upgrading, however, it is still worth reviewing:

• breaking changes,
• package compatibility,
• custom Backoffice extensions,
• OpenAPI configuration,
• Delivery API integrations,
• automated tests and CI/CD pipelines.

If the project contains custom Swagger or OpenAPI configuration, this area deserves particular attention.lną uwagę.

Source: CodeMasters – original illustration.

Umbraco 17 or Umbraco 18?

This is one of the most important questions surrounding the release.

Umbraco 17 is an LTS release. Umbraco 18 is an STS release.

For that reason, we would not recommend automatically moving every project to version 18 simply because it is newer.

Umbraco 17 is a natural choice when:

• the project is expected to run for many years,
• long-term support is the priority,
• Library and Elements are not currently required,
• you want to reduce the frequency of major upgrades.

Umbraco 18 makes particular sense when:

• you want to use Elements now,
• the project relies heavily on the Delivery API,
• you are comfortable with a shorter upgrade cycle,
• you are developing a product that regularly moves to new Umbraco versions.
  

Our recommendation

Umbraco 18 is not a release that every project needs simply because it has the highest version number.

That is actually a good thing.

Umbraco 17 remains a solid LTS release, and many platform improvements continue to be delivered there as well.

Umbraco 18 is interesting for a different reason: it introduces a new content concept that can change the way larger websites are designed.

Library and Elements solve a problem that Umbraco teams have historically approached in many different ways.

When starting a new project, it is now worth distinguishing between three concepts during content modelling:

Document – a page or routable piece of content.

Block – part of a page composition.

Element – independent, non-routable content intended for reuse.

Making that distinction results in a cleaner architecture and reduces the number of project-specific workarounds.

Summary

Umbraco 18 is a relatively small major release, but it introduces a feature with significant architectural potential.

The most important changes include:

• the new Library section,
• Elements as first-class content outside the document tree,
• the Element Picker,
• full lifecycle management for Elements,
• typed OpenAPI schemas for the Delivery API,
• the move from Swashbuckle to Microsoft.AspNetCore.OpenApi,
• improvements inherited from the Umbraco 17 release line.

The most interesting change, however, is not an individual API or Backoffice component.

It is finally being able to say:

“This content is not a page — and we no longer need to pretend that it is.”