Umbraco 16 is the next major version of Umbraco. It's the last short-term-support (STS) version before the next planned long-term-support (LTS) version of Umbraco 17.
Whilst 16 is a major version, it is mostly bringing you incremental improvements of the product, and as such, should be a straightforward upgrade for most. There's no new .NET version to contend with for this major. And the features and improvements are mostly wrapping up the effort we've put in over the past months to resolve issues and polish the new backoffice experience introduced with Umbraco 14.
We'll discuss in this post some of the things you should look out for when planning your upgrade, as well of course some of the benefits you'll get from updating to the latest Umbraco major.
In Umbraco 15, there were two property editors available for rich text editing - TinyMCE and Tiptap.
As previously announced, with Umbraco 16, only Tiptap is available as an option out of the box. TinyMCE's change of license precludes us from shipping a supported version with the MIT-licensed Umbraco CMS.
When upgrading to Umbraco 16, any data types using TinyMCE will be migrated to use Tiptap.
In Umbraco 15, as we are using the same schema for both property editors, you can update any existing rich text editor’s underlying data types to this new editor. When upgrading to the present release, this will happen automatically on upgrade.
Due to the common schema, the markup and blocks created by editors in your rich text editor content properties will be carried over. In your data type settings though, you will likely have to reconfigure the toolbar and other settings. Any bespoke plugins or purchased TinyMCE premium plugins will not be compatible with the new editor.
You can read more about using, configuring, and extending the Tiptap editor at the Umbraco documentation site.
To continue to use TinyMCE, a third-party package will need to be installed prior to the upgrade. That will disable the migration and allow you to continue with TinyMCE - either as a paid plugin or having accepted the license terms.
We are working closely with Umbraco and TinyMCE partner ProWorks to support the development of this package and expect it to as a release candidate before Umbraco 16 is released, and released shortly after.
Providing the best experience we can for editors is a point of pride for Umbraco CMS, and something developers and agencies focus on when providing solutions based on Umbraco.
We've focused on this in the improvements we've made to the backoffice over the course of the minor releases for Umbraco 15 - adding clipboard support for blocks, warnings for referenced content, drag/drop for media, and more robust validation.
Beyond this though, often customizations are made to the out-of-the-box editor experience that optimize it for a given project.
From Umbraco 14, the backoffice is extension-driven, with many elements customizable through supported extension points. What this has meant though is that some of the creative ways people have amended the backoffice experience in earlier versions were no longer available. This has been a deliberate decision - we want to support the extensions people need by allowing them to make them in ways we support (and importantly, don't unknowingly break with upgrades).
Over the course of Umbraco 15 minors and now in 16 we have made more of these extension points available, to allow some of the customizations available in earlier Umbraco versions to be made in new, supported ways.
You can customize which Document Types are available under a given node for the creation of new content via content type filters. Thus for example you can ensure that only a single "Settings" node can be created.
Property Value Presets are a client-side extension point allowing you to provide initial values for properties. Using these, based on whatever logic and data you make use of, you can pre-fill properties for editing when new documents are created.
Finally, we support the rendering of read-only and hidden properties, so you can mitigate against updates of important properties that shouldn't be seen or managed by some editor groups. Again, this is a client-side extension point that we've added to support custom logic for the feature. However, it's not only a developer-focused feature - as you'll read in the next section, we've surfaced the management of this for typical cases to the backoffice users section.
Umbraco has a permission system based on multiple features - user groups to allow management of access for groups of editors, and granular permissions for fine control of access to specific documents. With Umbraco 16, we are introducing a new granular permission for fine control over property-level access.
Each user group now has two new default permissions - the ability to read and write properties.
A migration will ensure that these are set to on for all existing user groups.
Then we have a new granular permission, allowing you to set these options for a particular property on a particular document type.
By disabling the "UI Write" option, the property will be presented readonly. Disabling "UI Read" will hide it from the editor's view.
It's important to call out that this feature is intended as an editor experience enhancement and not, at least at this stage, as a security measure. In other words, editors using the CMS will benefit from being presented with only the properties that they have a need to work with. But at the API level, all properties are passed and can be manipulated. As such, sensitive information should continue to be stored safely in configuration, key vault, etc., and not moved to managed content.
Content Segments are a little bit of a hidden feature in Umbraco - not something you are likely using directly in an Umbraco project, but nonetheless it's been a focus for us for Umbraco 16. They work in a similar way to content pages that have variants in different languages, providing another dimension for varying content for different website visitors.
We've added support for retrieving and updating segmented content via the management API and editing and previewing it via the backoffice. Block-level variation will support segmentation in an upcoming minor release for Umbraco 16.
They are typically used for marketing features such as personalization or A/B testing, and are key for the implementation of these in Umbraco Engage. They aren't restricted to that product though. Documentation for this is in the works, we’ll link here as soon as it’s ready, and look out for blog posts from our developer team on how you might utilize them in your own projects or packages.
With Umbraco 16, we're taking the opportunity for some rationalization of the payloads sent from CMS webhooks. Previously, they've been a little inconsistent in terms of what's included and excluded in the details sent.
We are introducing a new configuration option allowing more control over this, with three options:
Minimal - includes only the information required to identify the resources affected, providing identifiers to support retrieval of additional detail about the event as needed.
Extended - the minimal response, extended for certain webhooks with relevant information ready to consume.
Legacy - the current responses. This option is marked as obsolete, but is currently the default to ensure backward compatibility.
This update is still being worked on, so please look out for this in a subsequent release candidate for 16.
As is usual for a major upgrade, we've taken the opportunity to update all the dependencies Umbraco takes on the server and client to their latest, compatible versions. This had very little impact on the code of Umbraco itself, so we don't expect this to affect upgraded customer projects.
The specific dependency updates made for Umbraco 16 can be found in these PRs: for server-side and client-side libraries.
Other than the TinyMCE removal, breaking changes should be minimal in Umbraco 16. On the server-side, we've mostly limited such changes to the removal of already obsolete constructors and methods.
Client-side there are a few things to look out for if you've built extensions to the backoffice:
When consuming contexts, an undefined response will be resolved when the context can't be provided or the host is disconnected. See PR 19113 for more information.
Similarly, consuming a context as a promise can result in a promise rejection and getting a context can result in an undefined response. See PR 18611 for more information.
When making calls to retrieve data from the server, if you used either of Umbraco's helper methods tryExecute or tryExecuteAndNotify, then you need to adjust your code slightly. tryExecuteAndNotify is obsolete, and tryExecute takes the 'host' as the first argument. See PR 18939 for more information.
The full details of breaking changes can be found from this list of labelled PRs.
The new version of documentation for Umbraco 16 is ready at https://docs.umbraco.com/umbraco-cms.
For a full overview of all the features, improvements and fixes included in Umbraco 16 RC, and added since the previous minor release of 15, see the release notes.
To use the new release candidate, you can install the new Umbraco dotnet template and follow the installation documentation.
The prerelease packages are available from NuGet.
If you find issues that are not already reported, please report them on the GitHub issue tracker by following the link or selecting “🐛 Bug Report” when creating a new issue.
We plan to be rolling out additional release candidates to address minor bugs and incorporate feedback from the community. As we progress, these updates will primarily focus on fixing issues identified during testing.
In addition to resolving any bugs, our efforts will include making HQ packages like Umbraco Forms and Deploy available. We’re also prioritizing the availability of Umbraco 16 on Umbraco Cloud upon its release, along with ongoing documentation efforts.
We’re targeting the public release of Umbraco 16 for June 12, 2025.
We’re eager to hear your feedback on the Umbraco 16 Release Candidate - happy testing! 🙌
Umbraco Cloud continues to evolve, and if the first few months of 2025 are any indication, there’s plenty more in store. From regional hosting options to smoother workflows and scalable user access, the platform keeps getting stronger, more versatile, and even better suited for modern digital projects.