Expanding the backoffice search in Umbraco - Highlighting lesser known Umbraco features

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.