Umbraco 18 reaches general availability on June 25, 2026, with the release candidate already out for testing. If you run a site on Umbraco, this is the moment to look at your upgrade path: one genuinely new editor feature, a couple of API layer changes that developers will feel, and a short list of breaking changes worth clearing before you bump the version.

The new Library: a home for the elements you already use

First, a point of clarification, because it's easy to misread the headlines: Elements aren't new. Element types have been part of Umbraco for a long time. If you've built anything with the Block List or Block Grid editors, you've already been working with elements. What 18 adds is a new way to manage them: a dedicated Library section in the backoffice for reusable element content that lives outside the document tree.

In other words, this isn't a new concept landing at 18. It's a long-standing concept finally getting a proper management home, plus the capabilities that come with that.

Here's the problem it solves. For years, teams have leaned on documents to hold elements that aren't really pages: site settings, footer details, or a promo block reused in three places. All of it ends up modeled as a document somewhere, often tucked under a "Settings" or "Hidden" node, because the document tree was the only place to put it.

The Library gives that content a proper home and treats it as first-class content rather than a workaround. Within the Library, you get:

·        Reference tracking, so you know where an element is used before you change it

·        Workspace validation

·        Scheduled publishing

·        Rollback to earlier versions

·        Granular permissions

·        Audit logs

·        A recycling bin

·        Integration with global search

There's also an element picker you can lock down in two ways: by start node, and by user permissions, so you control which editors can reach the Library at all, and what they're allowed to do once they're in it. Day one, this is useful for the non-routable content that teams have been awkwardly modeling as pages for years.

One thing to set expectations on: the Library is phase one. The bigger vision (mixing and matching elements alongside standalone blocks in the Block Editor, converting existing blocks into reusable library elements, and customizing them per page) is targeted for Umbraco 19, later in 2026. So, treat the 18 Library as a strong foundation for managing shared and non-page content now, with the deeper editor-side integration arriving in the next major release.

Typed OpenAPI schemas for the Delivery API

For headless and decoupled builds, the Delivery API picks up an opt-in ability to generate typed OpenAPI schemas for each of your document types.

The nuance matters here, so be clear with your team about it: this only changes the OpenAPI document. The Delivery API responses themselves are identical to before. If you're calling the API directly, there's nothing new to gain; you can skip this entirely.

Where it pays off is client generation. With typed schemas in place, you can generate clients that match your content model instead of a generic, loosely typed blob:

·        TypeScript types for your front end

·        Swift models for native iOS work

·        C# DTOs for .NET consumers

If your stack generates clients from the spec, this is a quiet quality of life win. If it doesn't, it costs you nothing to leave off.

Swashbuckle is out, Microsoft.AspNetCore.OpenApi is in

Most editors will never notice this one. Package and extension developers absolutely will.

Umbraco 18 drops Swashbuckle in favor of the built-in Microsoft.AspNetCore.OpenApi. To smooth the transition, 18 ships a new helper, AddBackOfficeOpenApiDocument(), that rolls naming conventions, Swagger UI registration, and JSON serialization into a single call.

Two practical consequences:

1.     The OpenAPI endpoint moves from /umbraco/swagger/{documentName}/swagger.json to /umbraco/openapi/{documentName}.json. Any client-generation script pointed at the old path will need updating.

2.     If you maintain a package or a backoffice extension that wired up its own OpenAPI document, test it against the release candidate now, before the 25th, so you're not discovering a compile break on upgrade day.

Breaking changes worth clearing before you upgrade

Umbraco 18 also takes the opportunity to retire deprecated code. None of these are surprises if you've been tracking the deprecation warnings, but here's the shortlist to grep your solution for:

·        UmbracoApiController is gone - use the standard [ApiController] instead.

·        ILocalizationService is split into ILanguageService and IDictionaryItemService.

·        IFileService is split into four focused services.

·        More methods are async-only, so synchronous call sites will need updating.

·        IPublishedContent.Parent and .Children move to extension methods.

·        EnableMediaRecycleBinProtection now defaults to true - a config default shift to be aware of.

How to approach the upgrade

The smart move between now and June 25 is the same as every major: pull the RC into a branch, run your packages and custom extensions against it, and confirm your client generation and API integrations still behave. The breaking changes above are predictable; the OpenAPI endpoint move and the Swashbuckle swap are the two most likely to bite if you skip testing.

If you'd rather hand the upgrade to a team of Umbraco pros, that's exactly the kind of work we take on; get in touch, and we'll scope it with you.