Custom Picker Package Released Today

This release has been years in the making. Originally it be called "Api Picker" and required users to manually enter api paths when configuring , as the original version was developed over a year ago. It found its way into every project we have built since then and now we finally had a little time to package it up to share with the umbraco community.

What does it do?

Out of the box, not much, as a developer is needed to make the magic happen (though pre built pickers will be released by us and/or the community in the future). Once a developer has built/installed a picker though, editors can select data pulled from wherever the editor configured it to. Some examples of data sources we have worked with in the past are

  • 3rd party forms from hubspot and acton
  • Mailchimp lists
  • Content Types

It can be pretty powerful. One of the most complex use cases was for an import tool we built out. It allowed editors to set how content from a spreadsheet should be injected into the new pages when imported. A sample of that can be seen in the images below. Note how some of the options are greyed out, as those aren't selectable by the by the user.


Complex Custom Picker
Complex Custom Picker Panel (1)

But that's enough about the past. Lets talk about how to extend it.

How Do I Use It

Step 1 - Create the new picker class

Create a new class that extends one of the following base classes.

BasePicker - Used for synchronous data sources

public class ExamplePicker : BasePicker {

    public override Guid Key => new Guid("21696b2b-67fd-47a7-994f-596768e7ea17");
    public override string Name => "Example"; //This the used to identify the picker when creating a custom picker data type instance.

    public override IEnumerable<PickerOption> Children(string id, string culture) {

    public override IEnumerable<PickerOption> GetInfo(IEnumerable<string> ids, string culture) {

    public override IEnumerable<PickerOption> Search(string searchTerm, string culture) {


BaseAsyncPicker - Used for asynchronous data sources

public class ExampleAsyncPicker : BaseAsyncPicker {

    public override Guid Key => new Guid("2470e2dd-b784-4ef2-a879-cffd65a494e5");
    public override string Name => "Example Async"; //This the used to identify the picker when creating a custom picker data type instance.

    public override Task<IEnumerable<PickerOption>> ChildrenAsync(string id, string culture) {

    public override Task<IEnumerable<PickerOption>> GetInfoAsync(IEnumerable<string> ids, string culture) {

    public override Task<IEnumerable<PickerOption>> SearchAsync(string searchTerm, string culture) {


The Children and ChildrenAsync methods are used to content tree in the picker, where the id is the id of the parent content. The root id will always be "-1" This is the same approach umbraco uses for its TreeControllers (see here).

The GetInfo and GetInfoAsync methods are used to retrieve data about the currently selected items. This is needed since the control only stores the id, similar to how umbraco content pickers store a udi and pull in the relevent information from that.

The Search and SearchAsync methods are used to return a list of options matching the provided searchTerm.

See the code for the PickerPicker for a full implementation of a picker. This is the picker used to select the picker when creating the data type instance.

Step 2 - Create the custom picker instance

Create a new data type like usual, select the newly created picker for the picker property in the configuration and check "Allow Multiple" if more than one selection will be allowed at a time.

And that's all there is to it. For those that are interested there are two nuget packages for this package.

Your current browser is missing features this website requires to display correctly. Please upgrade your browser for the best experience.