umbraco-picker-data-source

Umbraco Picker Data Source

What is it?

A Picker Data Source provides data for picker-based property editors. It allows you to create custom data sources that supply items for content pickers, defining how items are fetched, searched, and displayed in a tree or collection format. This is useful for creating pickers that select from custom entities, external APIs, or filtered subsets of existing content.

Documentation

Always fetch the latest docs before implementing:

Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation
Extension Registry: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-registry
Property Editors: https://docs.umbraco.com/umbraco-cms/customizing/property-editors

Reference Example

The Umbraco source includes working examples:

Location: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/picker-data-source/

This example demonstrates multiple picker data source implementations:

Custom collection picker
Custom tree picker with search
Document picker with start node configuration
Media, Language, Webhook, and User pickers

Related Foundation Skills

Repository Pattern: For data fetching patterns

Reference skill: umbraco-repository-pattern

Tree: For tree-based picker data sources

Reference skill: umbraco-tree

Workflow

Fetch docs - Use WebFetch on the URLs above
Ask questions - What data to pick? Tree or collection? Search needed? Configuration options?
Generate files - Create manifest + data source class based on latest docs
Explain - Show what was created and how to use with a property editor

Manifest Example

import { UMB_PICKER_DATA_SOURCE_TYPE } from '@umbraco-cms/backoffice/picker-data-source';

Tree Picker Data Source

For hierarchical data with parent-child relationships:

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api'; import type { UmbPickerSearchableDataSource, UmbPickerTreeDataSource, } from '@umbraco-cms/backoffice/picker-data-source'; import type { UmbSearchRequestArgs, UmbSearchResultItemModel } from '@umbraco-cms/backoffice/search'; import type { UmbTreeChildrenOfRequestArgs, UmbTreeItemModel } from '@umbraco-cms/backoffice/tree';

export class MyPickerTreeDataSource extends UmbControllerBase implements UmbPickerTreeDataSource, UmbPickerSearchableDataSource { // Filter function to determine which items can be picked treePickableFilter: (treeItem: UmbTreeItemModel) => boolean = (treeItem) => !!treeItem.unique && treeItem.entityType === 'my-entity';

searchPickableFilter: (searchItem: UmbSearchResultItemModel) => boolean = (searchItem) => !!searchItem.unique && searchItem.entityType === 'my-entity';

// Return the root node (container for all items) async requestTreeRoot() { return { data: { unique: null, name: 'My Items', icon: 'icon-folder', hasChildren: true, entityType: 'my-entity-root', isFolder: true, }, }; }

// Return items at the root level async requestTreeRootItems() { const rootItems = myItems.filter((item) => item.parent.unique === null); return { data: { items: rootItems, total: rootItems.length, }, }; }

// Return children of a specific item async requestTreeItemsOf(args: UmbTreeChildrenOfRequestArgs) { const items = myItems.filter( (item) => item.parent.entityType === args.parent.entityType && item.parent.unique === args.parent.unique ); return { data: { items: items, total: items.length, }, }; }

// Return ancestors for breadcrumb navigation async requestTreeItemAncestors() { return { data: [] }; }

// Return specific items by their unique IDs async requestItems(uniques: Array<string>) { const items = myItems.filter((x) => uniques.includes(x.unique)); return { data: items }; }

// Search items by query string async search(args: UmbSearchRequestArgs) { const result = myItems.filter((item) => item.name.toLowerCase().includes(args.query.toLowerCase()) ); return { data: { items: result, total: result.length, }, }; } }

export { MyPickerTreeDataSource as api };

// Sample data const myItems: Array<UmbTreeItemModel> = [ { unique: '1', entityType: 'my-entity', name: 'Item 1', icon: 'icon-document', parent: { unique: null, entityType: 'my-entity-root' }, isFolder: false, hasChildren: false, }, { unique: '2', entityType: 'my-entity', name: 'Item 2', icon: 'icon-document', parent: { unique: null, entityType: 'my-entity-root' }, isFolder: false, hasChildren: false, }, ];

Collection Picker Data Source

For flat lists without hierarchy:

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api'; import type { UmbPickerCollectionDataSource } from '@umbraco-cms/backoffice/picker-data-source'; import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection';

export class MyPickerCollectionDataSource extends UmbControllerBase implements UmbPickerCollectionDataSource { async requestCollection() { const items: UmbCollectionItemModel[] = [ { unique: '1', entityType: 'my-entity', name: 'Item 1', icon: 'icon-document' }, { unique: '2', entityType: 'my-entity', name: 'Item 2', icon: 'icon-document' }, { unique: '3', entityType: 'my-entity', name: 'Item 3', icon: 'icon-document' }, ];

return {
  data: {
    items,
    total: items.length,
  },
};

}

async requestItems(uniques: Array<string>) { // Return specific items by unique IDs const allItems = await this.requestCollection(); const items = allItems.data.items.filter((x) => uniques.includes(x.unique)); return { data: items }; } }

export { MyPickerCollectionDataSource as api };

Data Source with Configuration

Add settings to your picker data source:

export const manifests: Array<UmbExtensionManifest> = [ { type: 'propertyEditorDataSource', dataSourceType: UMB_PICKER_DATA_SOURCE_TYPE, alias: 'My.PropertyEditorDataSource.ConfigurablePicker', name: 'Configurable Picker Data Source', api: () => import('./my-configurable-picker-data-source.js'), meta: { label: 'Configurable Items', icon: 'icon-settings', description: 'Pick items with configuration options', settings: { properties: [ { alias: 'startNode', label: 'Start Node', description: 'Select where to start picking from', propertyEditorUiAlias: 'Umb.PropertyEditorUi.ContentPicker.Source', }, { alias: 'filter', label: 'Filter Types', description: 'Select which types can be picked', propertyEditorUiAlias: 'Umb.PropertyEditorUi.ContentPicker.SourceType', }, ], }, }, }, ];

Interfaces

interface UmbPickerTreeDataSource { treePickableFilter?: (treeItem: UmbTreeItemModel) => boolean; requestTreeRoot(): Promise<{ data: UmbTreeItemModel }>; requestTreeRootItems(): Promise<{ data: { items: UmbTreeItemModel[]; total: number } }>; requestTreeItemsOf(args: UmbTreeChildrenOfRequestArgs): Promise<{ data: { items: UmbTreeItemModel[]; total: number } }>; requestTreeItemAncestors(): Promise<{ data: UmbTreeItemModel[] }>; requestItems(uniques: string[]): Promise<{ data: UmbTreeItemModel[] }>; }

interface UmbPickerSearchableDataSource { searchPickableFilter?: (searchItem: UmbSearchResultItemModel) => boolean; search(args: UmbSearchRequestArgs): Promise<{ data: { items: UmbSearchResultItemModel[]; total: number } }>; }

interface UmbPickerCollectionDataSource { requestCollection(): Promise<{ data: { items: UmbCollectionItemModel[]; total: number } }>; requestItems(uniques: string[]): Promise<{ data: UmbCollectionItemModel[] }>; }

Key Concepts

Concept Description

dataSourceType

Must be UMB_PICKER_DATA_SOURCE_TYPE for picker data sources

treePickableFilter

Function to determine which tree items can be selected

searchPickableFilter

Function to determine which search results can be selected

requestItems

Returns items by their unique IDs (for displaying selected values)

entityType

Identifies the type of entity (used for filtering and routing)

Best Practices

Implement search - Users expect to search in pickers with many items
Use appropriate icons - Help users identify item types visually
Filter pickable items - Not all tree items should be selectable (e.g., folders)
Handle configuration - Support start nodes and type filters when applicable
Return consistent data - Ensure requestItems returns the same format as tree/collection

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.

umbraco-picker-data-source

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

umbraco-backoffice

umbraco-dashboard

umbraco-quickstart