Umbraco 18 Release Candidate

This Release Candidate follows on from the beta releases that started a couple of weeks ago. Since then, we've spent the time looking into reported issues, bringing in some additional bug fixes, and generally polishing to get to the point of releasing the RC today. That'll continue over the next period, but we'll be limiting change now to only the resolution of issues found or reported in regression testing.

Umbraco 18 has a familiar shape to it: one headline feature that arrives in its first stage, a handful of focused improvements, and a steady stream of polish underneath. There's a fair bit to cover, so I've split this post into three. First, what's new in 18 that you'll see when you upgrade. Then a look at some work in progress that's worth knowing about, even though it isn't in the release. And finally, a quick recap of things that have landed in the 17.x minor releases you may not have caught, and will be available in Umbraco 18 as well.

What's new in 18

Elements - Phase One

The main new feature in 18 is Elements: a way to manage reusable content that lives outside the document tree.

For some time now, editors have leaned on documents to hold things that aren't really pages — site-wide settings, footer data, reusable promotion blocks, and so on. It works, but it stretches what documents are designed for, and it doesn't give editors a clear mental model for "this isn't a page, it's a piece of content I want to reuse."

What you'll find in 18 is the foundation for Elements: a dedicated Library section in the backoffice for managing elements, which exhibit all the features you'd expect from a first-class content type — reference tracking, workspace validation, scheduled publishing, rollback, permissions, audit logs, recycle bin, and global search integration.

We also provide an element picker, configurable by start node, along with user permissions to control which editors can access the Library, and what they can do within it.

Already this is useful for non-routable content that editors need to manage — settings, taxonomy-style data, anything you'd rather not have to model as a page.

See how to define element types, prepare and publish element instances and associate them with pages using the element picker.

It is, however, phase one of a larger feature. The bigger payoff — being able to mix and match Elements alongside standalone blocks in the Block Editor, convert blocks into reusable library elements, and customize them per page — is targeted for Umbraco 19 later in 2026. If you'd like the full picture of where this is heading, the Q1 2026 product update walks through the roadmap.

Typed OpenAPI schemas for the Delivery API

The Delivery API now has an opt-in option to generate typed OpenAPI schemas for each Document Type, Element Type, and Media Type in your project. Enable it via configuration, and the OpenAPI document will include dedicated schemas for each content type, expressed as a discriminated union keyed on contentType (or mediaType for media).

It's worth being clear that this only changes the OpenAPI document — the Delivery API responses themselves are unchanged. So if you're consuming the API directly, there's nothing to gain. If you're generating clients from the specification, though, there's a real benefit: TypeScript types, Swift models, or C# DTOs can now be shaped to your actual content model, rather than a loosely-typed bag of properties, with concrete property access once you narrow on the discriminator.

One caveat — the schemas use OpenAPI 3.1 patterns (oneOf with discriminators and allOf), and not every client generator supports those equally well, so it's worth verifying the output against your chosen tool before relying on it in production. The content type schemas in OpenAPI documentation walk through the details with a configuration example and sample TypeScript usage.

Replacing Swashbuckle with Microsoft.AspNetCore.OpenApi

The other big change in 18 is one most editors will never see, but package and extension developers will want to read carefully: we've replaced Swashbuckle with the built-in Microsoft.AspNetCore.OpenApi.

The motivation is reasonably straightforward — fewer third-party dependencies, native OpenAPI 3.1 support, and a more sustainable path forward as the .NET platform evolves. The practical impact, though, is that any extension that wired up its own OpenAPI document on Umbraco 17 won't compile against Umbraco 18, because the Swashbuckle types it relied on are gone.

For most cases, the migration is small. Umbraco 18 ships a new helper, AddBackOfficeOpenApiDocument( ), that handles naming conventions, Swagger UI registration, and JSON serialization in one call. The OpenAPI endpoint also moves from /umbraco/swagger/{documentName}/swagger.json to /umbraco/openapi/{documentName}.json, so any client-generation scripts you have will need updating.

If you maintain a package or backoffice extension, this is one to test against the RC. Laura Neto has written a practical heads-up for extension developers that walks through exactly what changes and how to adapt.

Other breaking changes

There are a handful of other breaking changes in 18 where we have taken the opportunity to remove deprecated code. UmbracoApiController is gone in favor of standard [ApiController], ILocalizationService is split into ILanguageService and IDictionaryItemService, IFileService splits into four focused services, more methods are async-only, IPublishedContent.Parent and .Children move to extension methods, and a few configuration defaults shift (notably, EnableMediaRecycleBinProtection is now true).

Rather than enumerate them all here, the version-specific upgrade documentation contains the full details. When you come to upgrade your projects, that's the page to bookmark.

Things in Umbraco 17 you may have missed

A fair bit has shipped in the 17.x minor releases - up to and including 17.5, which ships alongside 18.0. If you're on an earlier minor, it's worth catching up on what's been added since, all of which you'll also find in 18.

Better support for AI

17.4 introduced JSON Schema endpoints for the Management API, which can be a great help for AI tools interacting with the API. Until now, a tool like Umbraco MCP had no reliable way to know the shape of a property's value.

With schema endpoints in place, an LLM, or indeed any external tool, can request the schema for a Data Type or Document Type, understand the required structure, and construct valid values deterministically - rather than guessing and hoping the API accepts what's been generated. Combined with a new document patch endpoint, that improves AI-driven content editing from "best effort" into something you can much more safely rely on.

Matt Brailsford has written about why this is a big deal for AI, and it's worth reading if you're building or using AI integrations on top of Umbraco.

Configurable website output caching

17.4 added server-side output caching for template-rendered pages, with intelligent invalidation based on content keys, ancestors, content types, and related items. Turn it on via configuration, and concurrent requests within the cache window collapse into a single render - so CPU stops scaling linearly with traffic spikes, and cache eviction happens automatically when content publishes.

It's opt-in, configurable, and pairs neatly with the corresponding extension points added to the Delivery API. See the website output caching documentation for the details.

Lightweight external-only members

If you authenticate members through Entra ID, Auth0, Google, or any other external identity provider, the new lightweight external-only members option is worth a look. Instead of storing each member as a full content entity, with versions, content table writes, and search re-indexing on every registration, Umbraco can now keep just a minimal identity record with the fields needed for authentication and role membership.

The result is much better throughput under high-concurrency login and registration scenarios, because you're no longer hitting write contention on content tables and search indexes. The trade-off is that you can't edit profiles in the backoffice or store member-specific content properties, which is appropriate when the external provider is the source of truth for member identity. The lightweight external members documentation has the full picture.

Modular Umbraco deployments

17.3 introduced the ability to run Umbraco with different combinations of the backoffice, website front-end, and Delivery API enabled or disabled. So you can deploy a backoffice-only authoring environment, a front-end-only delivery environment, or any other combination that fits your topology, useful for scaling, isolating concerns, or reducing the attack surface of public-facing nodes.

17.4 followed up with a standalone login page for front-end-only deployments, so authentication still works when there's no backoffice running, useful, for example, when protecting a restricted environment with Basic Authentication. Together, these give a lot more flexibility in how a multi-environment Umbraco deployment can be architected.

Load balancing improvements

Load balancing the backoffice was a standout feature in Umbraco 17, and we've improved that support over the subsequent releases. A couple of performance concerns have been resolved, and we've added configurable SignalR transport settings, making it possible to run load-balanced deployments where session stickiness isn't available or desired.

Background jobs and operability

Unattended upgrades - the migrations that run automatically when you deploy a new version - moved into a background task, with liveness and readiness health probes signalling whether the application is ready to take traffic. For containerized or autoscaled deployments, where a slow startup migration could otherwise cause cascading failures or premature restarts, this provides a nice operability improvement.

Distributed background jobs now pass the cancellation token through to job implementations, so long-running work can shut down gracefully when the application stops, rather than being abandoned mid-execution. Recurring background jobs also gain on-demand triggering, with control over what happens to the next scheduled execution. Pending documentation for the background jobs updates is available in this pull request to the docs repo.

On the database side, a new SQL Server health check detects untrusted foreign key and check constraints - a condition that can quietly hurt query optimizer performance and which is seen on upgraded sites following historical use of bulk imports. The check surfaces in the existing health check dashboard so it's easy to spot and remediate.

Performance improvements

If you've upgraded through the 17.x minors, you will have picked up a long list of performance improvements. These include work to reduce and de-duplicate backoffice requests, and optimizations for front-end rendering and backoffice operations. All of these are wrapped up and available in 18.

Backoffice improvements

Across the 17.x minors and into 18, we've also brought many editor-experience improvements, including:

• Icon thesaurus: the icon picker now supports keyword search using alternative names, so searching for "picture" finds the image icon rather than nothing.

• Media cards and table views: a view switcher in the media picker, so editors can choose between cards and a denser table view.

• Inline folder creation and selection in pickers: media and entity pickers now support creating folders inline, and selecting a folder itself rather than only its contents — handy when the folder is what you actually want to reference.

• Thumbnail generation by file extension: smarter thumbnails that respect file type, so non-image media gets a useful preview.

• User group descriptions: a small thing, but groups can now carry a description, which is useful when "Editors" and "Senior Editors" need explaining to a new team member.

• Current user workspace: a dedicated modal for managing your own profile, so you no longer have to ask an administrator to update your preferred language.

• Document picker breadcrumbs: search results in the document picker now show the ancestor breadcrumb path, so it's clear which "Home" or "Settings" you're picking when several documents share a name.

• Rich text editor: the Tiptap RTE now supports resizing images and embeds.

• New extension points for backoffice developers: a Block Action extension type lets package authors add custom actions to individual blocks in the Block List and Block Grid editors, and new Value Type and Value Summary extensions let you customize how property values are displayed in summary contexts like card and collection views.

Alongside the visible features, there's been a steady stream of accessibility work across the backoffice, labels added to controls that were previously missing them, improvements to keyboard navigation, and small refinements that make the experience smoother for screen-reader users. It's not the kind of work that headlines a release, but it adds up.

Community contributions

Two of the items above have particularly nice community stories behind them.

Lightweight external members started as Jeroen Breuer's "virtual members" proof-of-concept back in 2022, a community experiment that identified a real problem and eventually landed in core in 17.4. Jeroen wrote about the journey from community PR to shipped feature, and it's a good read.

The icon thesaurus has an even longer arc. Joe Glombek started Umbicosaurus back in 2021 as a package, with contributions to the icon dictionary from various community members. After it stalled in 2022, categorizing hundreds of icons turning out to be more work than any one person could realistically finish, Niels Lyngsø reached out about bringing the idea into core, where it could benefit from broader community maintenance. The thesaurus shipped in 17.4 with fuzzy search added on top. Joe has written about Umbicosaurus's de-extinction and it's a lovely example of how community and core work meet.

Try the RC and let us know what you find

Between now and the 25th of June, we'd really value your help testing the RC against real projects, packages and websites.

If you do find anything, after a quick look to see if the problem is already reported, please provide details in the CMS tracker, indicating which version you've discovered an issue in.

You'll find the release candidate on NuGet and details of the release on both GitHub and releases.umbraco.com.

And, as always, thank you to everyone who has contributed code, ideas, bug reports, and conversations to this release.