DEV Community: Bernadet Goey

Umbraco 2-way relations - Umbraco Features You Didn't Know You Needed

Bernadet Goey — Mon, 31 Aug 2026 09:47:52 +0000

Relations in Umbraco: asking the question your picker can't answer

You've probably used a Content Picker (or a Multinode Treepicker) to wire content together. A page picks a banner, a landing page picks a set of related articles, a policy picks the older policy it replaces. That gives you one direction for free: open the page, and you can see exactly what it points at.

But pickers only answer one question. "What does this page use?" is easy. "What uses this?" is not. The picker property lives on the node that did the picking, not on the node that got picked. If you want to go the other way, your only option is make the pages hierarchical or to loop over every piece of content in the tree and check whether its picker field happens to mention the node you care about.

That's exactly the gap Umbraco's Relations are for. A Relation is a first-class, queryable link between two entities that you can walk in either direction via IRelationService: GetByParentId for "what does this point at", GetByChildId for "what points at this". This post walks through a small example project that uses a Relation to answer a question a picker alone can't.

The scenario: policies that supersede each other

Imagine a "Policy Page" doctype. Editors write a new policy, and pick (via a normal Multinode Treepicker) which older policy or policies it supersedes. That's a completely standard one-way relationship: new policy → picks → old policy.

The picker answers "which policies does this one supersede" perfectly well. What it can't answer is the question an editor actually asks when they land on an old policy page: "Has this been superseded, and by what?" Nothing on that old policy's own data points back to the newer one — the pick lives entirely on the other node. Short of scanning every Policy Page in the site for one whose supersedes field happens to mention this node's ID, there's no way to answer it.

Why not just use Umbraco's built-in "Related Document" relation?

Umbraco ships a built-in relation type for exactly this kind of document-to-document link, aliased umbDocument. It would technically work — except it's a single shared, undifferentiated bucket. Anything in Umbraco (media picker usages, link pickers, whatever else) can write a generic document-to-document reference into it, so a reverse lookup on umbDocument can't reliably tell you "which policy superseded this one" versus any other unrelated reference someone else recorded into the same bucket.

The fix is a relation type of your own policySupersedes so a reverse lookup on that alias only ever returns the thing you actually care about.

The implementation

The example lives in four files.

1. The doctype and the picker. Add a "Policy Page" content type with a bodyText richtext property and a supersedes Multinode Treepicker, filtered so it can only pick other Policy Pages.

This is the plain, one-way picker. Nothing special yet.

2. Syncing the picker into a Relation. PolicySupersedesRelationSyncHandler listens for ContentSavedNotification. Every time a Policy Page is saved, it wipes out whatever relations already exist for that node under the policySupersedes alias and rebuilds them from whatever's currently picked:

    public void Handle(ContentSavedNotification notification)
    {
        foreach (IContent content in notification.SavedEntities)
        {
            if (content.ContentType.Alias == PolicyPageContentTypeAlias)
            {
                SyncSupersedesRelations(content);
            }
        }
    }

    private void SyncSupersedesRelations(IContent newPolicy)
    {
        IRelationType relationType = _relationService.GetRelationTypeByAlias(ExampleConstants.RelationTypeAlias)
            ?? CreateRelationType();

        foreach (IRelation existingRelation in _relationService.GetByParentId(newPolicy.Id, ExampleConstants.RelationTypeAlias))
        {
            _relationService.Delete(existingRelation);
        }

        foreach (int supersededPolicyId in GetPickedContentIds(newPolicy))
        {
            var relation = new Relation(newPolicy.Id, supersededPolicyId, relationType)
            {
                Comment = $"Marked as superseded on {DateTime.UtcNow:u}",
            };
            _relationService.Save(relation);
        }
    }

As shown above, you can also add a comment to a relation, which we use to store additional information on when the policy was superseded in our example, which can then be shown again on the Policy page.

The relation type itself is created on demand as non-bidirectional, Document-to-Document, and importantly isDependency: true:

    private IRelationType CreateRelationType()
    {
        var relationType = new RelationType(
            "Policy Supersedes",
            ExampleConstants.RelationTypeAlias,
            isBidrectional: false,
            parentObjectType: Constants.ObjectTypes.Document,
            childObjectType: Constants.ObjectTypes.Document,
            isDependency: true,
            key: null);
        _relationService.Save(relationType);
        return relationType;
    }

3. Wiring it up. Add the notification handler with the standard IComposer boilerplate, nothing Relations-specific.

4. Reading both directions in the view. This is where the payoff shows up. policyPage.cshtml reads the picker property directly for the forward direction, and calls RelationService.GetByChildId for the reverse direction, the direction the picker alone could never give you:

var supersededByRelations = RelationService.GetByChildId(Model.Id, ExampleConstants.RelationTypeAlias);

@if (supersededByRelations.Any())
{
    <div style="border: 2px solid red; padding: 1em; margin-bottom: 1em;">
        <strong>This policy has been superseded.</strong>
        <ul>
            @foreach (var relation in supersededByRelations)
            {
                var newerPolicy = ContentQuery.Content(relation.ParentId);
                if (newerPolicy is not null)
                    {
                        <li>
                            Replaced by <a href="@newerPolicy.Url()">@newerPolicy.Name</a>
                            <br />
                            <small>@relation.Comment</small>
                        </li>
                    }
            }
        </ul>
    </div>
}

Open an old policy that's been superseded, and the page now knows it without ever scanning the rest of the tree.

The other payoff: you can't delete a still-referenced policy without a warning

Setting IsDependency = true on the relation type isn't just documentation, it plugs straight into Umbraco's own dependency checks. Try to delete or unpublish a policy that's still marked as superseded by another one, and the backoffice will warn you it's in use, the same way it would for a media item still referenced by a Content Picker elsewhere.

This is the practical version of "what if you need to delete a shared component, but three pages still reference it": with a plain picker, deleting the referenced item is silent and the reference just breaks. With a proper Relation, Umbraco already knows something depends on it and stops you.

When to reach for this

A picker is enough when you only ever need to ask "what does this content point at", the normal, forward direction.
The built-in "Related Document" relation is fine for generic, low-stakes cross-references where you don't care about precision on the reverse lookup.
A custom relation type is worth the extra notification-handler code when you need a reverse lookup you can trust "what points at me" and/or you want deletion/unpublish safety for content that's still depended on.

Pickers tell you what a page uses. Relations are what let you ask the question in the other direction.

Expanding the backoffice search in Umbraco - Umbraco Features You Didn't Know You Needed

Bernadet Goey — Fri, 07 Aug 2026 12:53:14 +0000

Recently, I started using Erik-Jan Westerndorp's community package "Heading". on a project. It’s one of those packages that solves a very specific problem really neatly.

In this case, the client wanted editors to be able to choose the heading level for a title on an element. So, for example, one image block might need an H2, while another might need an H3, depending on where it sits on the page.

The package worked great for that.

But, as often happens, solving one problem uncovered another.

Not long after, the client came back with a new bit of feedback:

I can’t search for the custom title I’ve added.

And honestly, my first reaction was: surely that should just work?

So I gave it a try - and they were right. The backoffice document search was only finding results based on the page name, not on values stored in custom fields.

Searching by page name returns the page
Searching by page title returns no results

The first thing I did was check the internal index — and the title field was there, so that allowed me to cross off one possible issue.

So the content was being indexed - it just wasn’t being searched by the backoffice search.

I asked a few colleagues about it, and the general feeling was that this probably wasn’t something you could change. The assumption was that Umbraco backoffice search just searches a predefined set of fields and that was that.

Still, it felt like there had to be a way.

And there is.

The Missing Piece: UmbracoTreeSearcherFields

It turns out this is already supported and documented, but it was a feature I hadn’t come across before. Since I suspect I’m not the only one, it’s worth highlighting here:

Backoffice Search - A guide to customization of Backoffice Search

That article introduced me to UmbracoTreeSearcherFields, which controls the indexed fields used by backoffice search. By replacing it with a custom implementation, you can expand the list of searchable fields.

My first attempt looked like this:

public class CustomUmbracoTreeSearcherFields(ILanguageService languageService)
    : UmbracoTreeSearcherFields(languageService), IUmbracoTreeSearcherFields
{
    public new IEnumerable<string> GetBackOfficeDocumentFields()
    {
        return new List<string>(base.GetBackOfficeFields()) { "title" };
    }
}

I restarted my environment, tried again… and it still didn’t work.

Backoffice search could still only find the page by name.

The Catch: Variant Field Names

After taking a closer look at the index, the reason became clear: the field key wasn’t simply title. Because the property had language variants, the indexed field name includes the language ISO code.

So instead of hardcoding a single field name, I updated the implementation to generate the variant field names dynamically. That also makes it more future-proof — if new languages are added later, search continues to work without any code changes.

Here’s the updated version:

public class CustomUmbracoTreeSearcherFields(ILanguageService languageService)
    : UmbracoTreeSearcherFields(languageService), IUmbracoTreeSearcherFields
{
    private static readonly string TitleAlias = PublishedModelHelper.GetModelPropertyAlias((Page x) => x.Title);

    public override IEnumerable<string> GetBackOfficeDocumentFields()
    {
        return base.GetBackOfficeDocumentFields().Concat(GetVariantFieldNames(TitleAlias));
    }

    private IEnumerable<string> GetVariantFieldNames(string alias)
        => languageService.GetAllAsync().GetAwaiter().GetResult().Select(l => $"{alias}_{l.IsoCode.ToLowerInvariant()}");
}

And with that in place, the backoffice search started returning results based on the custom title value as well.

Why I’m sharing this

This is one of those things that’s probably obvious once you’ve worked with it before, but until then, it’s easy to assume backoffice search is less flexible than it actually is.

If you’ve got editors relying on custom fields it’s worth checking whether those fields are included in backoffice search. If they’re already indexed, you may only need to extend UmbracoTreeSearcherFields to make them searchable.

A small change, but a very useful one for editors.

Extending Tiptap in Umbraco – a real world list example

Bernadet Goey — Tue, 23 Jun 2026 07:37:36 +0000

If you've spent any time migrating editors or building rich-text features, you'll know Tiptap looks great on paper but sometimes feels a little... minimal compared to what TinyMCE shipped out of the box. At ilionx we've been moving a few large sites to Umbraco 17 and bumped into the same feedback: list style options. Nothing dramatic, just the ability to pick Roman numerals, different bullet shapes, that sort of thing, but enough to make editors ask for the old behavior back.

So we wrote a small TypeScript extension that adds back list-style variants. It gets built to App_Plugins with Vite, plugs into the UmbTiptapExtensionApiBase and wires up extra toolbar menu items. The actual extension is tiny, it just adds a listStyleType attribute to the list nodes and renders it as inline CSS, but the surrounding bits (icons, toolbar menus, wiring) make the UX feel polished.

Tiptap has solid docs on extending and creating extensions, and Umbraco documents how to register a Tiptap extension, but stitching everything together took a little trial and error. Below is the extension configuration we used. It looks like a lot for a simple feature, but a fair chunk of the files are just icons and small glue code.

Let’s start with the actual extension definitions in Umbraco-package.json, where we define 4 extensions:

"extensions": [
  {
    "type": "icons",
    "alias": "My.Icons.TiptapListStyle",
    "js": "/App_Plugins/My.TiptapListStyle/list-style-icons.js"
  },
  {
    "type": "tiptapExtension",
    "alias": "My.Tiptap.ListStyle",
    "api": "/App_Plugins/My.TiptapListStyle/list-style.tiptap-api.js",
    "meta": {
      "icon": "icon-ordered-list",
      "label": "List style type",
      "group": "#tiptap_extGroup_formatting"
    }
  },
  {
    "type": "tiptapToolbarExtension",
    "kind": "menu",
    "alias": "My.Tiptap.Toolbar.OrderedList",
    "overwrites": "Umb.Tiptap.Toolbar.OrderedList",
    "api": "/App_Plugins/ My.TiptapListStyle/ordered-list-menu.tiptap-toolbar-api.js",
    "forExtensions": ["My.Tiptap.ListStyle", " My.Tiptap.OrderedList"],
    "items": [
      {
        "label": "Numbered list",
        "data": null,
        "appearance": { "icon": "icon-ordered-list" }
      },
      {
        "label": "Numbered list: i, ii, iii",
        "data": "lower-roman",
        "appearance": { "icon": "icon-list-style-lower-roman" }
      },
      // add other style definitions here
    ] 
  },
  {
    "type": "tiptapToolbarExtension",
    "kind": "menu",
    "alias": " My.Tiptap.Toolbar.BulletList",
    "overwrites": "Umb.Tiptap.Toolbar.BulletList",
    "api": "/App_Plugins/My.TiptapListStyle/bullet-list-menu.tiptap-toolbar-api.js",
    "forExtensions": ["My.Tiptap.ListStyle", "Umb.Tiptap.BulletList"],
    "items": [
      {
        "label": "Bullet list",
        "data": null,
        "appearance": { "icon": "icon-bulleted-list" }
      },
      {
        "label": "Bullet list: circle",
        "data": "circle",
        "appearance": { "icon": "icon-list-style-bullet-circle" }
      },
      // add other style definitions here
    ]
  }
]

Here’s what we register:

an icon set (a bunch of tiny SVGs showing what each list style looks like)
one Tiptap extension which carries the list-style attribute
two toolbar extensions that replace the ordered/bulleted list buttons with menus that expose the variants.

The icon set

The icons are trivial: I asked an AI to generate SVGs for different list markers and put each one in a tiny TypeScript file that exports the SVG string.

/** Ordered list with lower-roman markers (i, ii, iii). */
export default `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.75"><text x="1" y="7.5" font-size="4.5" fill="currentColor" stroke="none" font-family="serif" font-style="italic">i.</text><path d="M9 6h12"/><text x="1" y="13.5" font-size="4.5" fill="currentColor" stroke="none" font-family="serif" font-style="italic">ii.</text><path d="M9 12h12"/><text x="1" y="19.5" font-size="4.5" fill="currentColor" stroke="none" font-family="serif" font-style="italic">iii.</text><path d="M9 18h12"/></svg>`;

And a small registry file maps the icon names to those files:

export default [
  {
    name: 'icon-list-style-lower-roman',
    path: () => import('./icons/svg-ordered-list-lower-roman.js'),
  },
    //...
];

These images are purely to make the toolbar menus readable — a little UX polish so editors instantly recognise the option they’re picking.

The Tiptap extension

The extension itself is surprisingly compact. It adds a listStyleType attribute to the built-in orderedList and bulletList nodes and serialises it as inline list-style-type style so the HTML stays portable and renders the same in the backoffice and on the front end.

import { Extension, UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';

/**
 * Extends the built-in orderedList and bulletList nodes with a `listStyleType`
 * attribute that maps to the CSS `list-style-type` property.
 *
 * The attribute is serialised as an inline style so the stored HTML is portable
 * and renders correctly both in the backoffice editor and on the front end.
 */
const ListStyleExtension = Extension.create({
  name: 'listStyle',

  addGlobalAttributes() {
    return [
      {
        types: ['orderedList', 'bulletList'],
        attributes: {
          listStyleType: {
            default: null,
            parseHTML: (element) => element.style.listStyleType || null,
            renderHTML: (attributes) => {
              if (!attributes['listStyleType']) return {};
              return { style: `list-style-type: ${attributes['listStyleType']}` };
            },
          },
        },
      },
    ];
  },
});

export default class ListStyleTiptapExtensionApi extends UmbTiptapExtensionApiBase {
  constructor(...args: ConstructorParameters<typeof UmbTiptapExtensionApiBase>) {
    super(...args);
    this.getTiptapExtensions = () => [ListStyleExtension];
  }
}

That’s it, the extension maps an attribute to CSS and makes sure works in both front- and backoffice. Nothing scary.

The toolbar extensions

Because ordered and unordered lists are separate toolbar buttons, we overwrite each one with a menu that exposes the style variants. To avoid duplicating logic we put the toolbar behaviour into a single helper and import it from the two small extension files.

Each toolbar menu has to do a few things:

create a list if the selection isn’t in one
switch between ordered and bullet lists
toggle or set a specific list-style-type and reflect the active state in the menu UI.

That last bit is where the logic concentrates, the UI needs to show which style is active and allow toggling back to the default behaviour.

The per-list-type extension files look like this:

import { createListStyleMenuToolbarApi } from './list-style-menu-toolbar-api.js';

export default createListStyleMenuToolbarApi('bulletList');

And the shared toolbar helper contains the actual implementation and state logic:

import type { Editor } from '@umbraco-cms/backoffice/tiptap';
import { UmbTiptapToolbarElementApiBase } from '@umbraco-cms/backoffice/tiptap';

type ListStyleMenuItem = { data?: string | null };

function getStyleType(item?: ListStyleMenuItem): string | null | undefined {
  return item?.data;
}

function applyListStyle(
  editor: Editor,
  listType: 'orderedList' | 'bulletList',
  styleType: string,
): void {
  if (editor.isActive(listType)) {
    const currentStyle = editor.getAttributes(listType)['listStyleType'] as string | null;
    const newStyle = currentStyle === styleType ? null : styleType;
    editor.chain().focus().updateAttributes(listType, { listStyleType: newStyle }).run();
    return;
  }

  if (listType === 'orderedList') {
    editor
      .chain()
      .focus()
      .toggleOrderedList()
      .updateAttributes('orderedList', { listStyleType: styleType })
      .run();
  } else {
    editor
      .chain()
      .focus()
      .toggleBulletList()
      .updateAttributes('bulletList', { listStyleType: styleType })
      .run();
  }
}

function applyDefaultList(editor: Editor, listType: 'orderedList' | 'bulletList'): void {
  if (editor.isActive(listType)) {
    const currentStyle = editor.getAttributes(listType)['listStyleType'] as string | null;
    if (currentStyle) {
      editor.chain().focus().updateAttributes(listType, { listStyleType: null }).run();
      return;
    }
    if (listType === 'orderedList') {
      editor.chain().focus().toggleOrderedList().run();
    } else {
      editor.chain().focus().toggleBulletList().run();
    }
    return;
  }

  if (listType === 'orderedList') {
    editor.chain().focus().toggleOrderedList().run();
  } else {
    editor.chain().focus().toggleBulletList().run();
  }
}

/**
 * Toolbar menu API for ordered/bullet list buttons with list-style-type variants.
 */
export function createListStyleMenuToolbarApi(listType: 'orderedList' | 'bulletList') {
  return class extends UmbTiptapToolbarElementApiBase {
    override isActive(editor?: Editor, item?: ListStyleMenuItem): boolean {
      if (!editor) return false;

      const styleType = getStyleType(item);
      if (styleType === undefined) {
        return editor.isActive(listType);
      }

      if (styleType === null) {
        const currentStyle = editor.getAttributes(listType)['listStyleType'] as string | null;
        return editor.isActive(listType) && currentStyle === null;
      }

      return editor.isActive(listType, { listStyleType: styleType });
    }

    override execute(editor?: Editor, item?: ListStyleMenuItem): void {
      if (!editor) return;

      const styleType = getStyleType(item);
      if (styleType === undefined || styleType === null) {
        applyDefaultList(editor, listType);
        return;
      }

      applyListStyle(editor, listType, styleType);
    }
  };
}

TODO / caveats

I’m still getting comfortable with TypeScript, so this isn't a 100%-polished extension. One known quirk: clicking a custom style button after setting a style will clear the style but not fully remove the list node the way the stock ordered/bullet button does. It's a small UX edge-case and likely fixable by tweaking the toggle logic, but I haven't had time for it yet.

If you want to copy this approach, the important bits are:

expose a listStyleType attribute on the list nodes,
serialize it in a way that works in both editor and front end (inline style is the simplest)
replace the toolbar buttons with menus that set/update that attribute.

Hopefully this saves you a few hours of experimentation. The overall idea is small, but the payoff for editors is surprisingly nice.