Add Value Type

Add a new value type constant to UmbValueTypeMap.

Foundational documentation

Read before proceeding:

• Value Type — full reference, naming convention, rules

What you need from the user

1. Feature name — kebab-case (e.g., color-picker, user-group)
2. Package path — where the feature lives (e.g., src/packages/property-editors/color-picker/)
3. Value type key — the string alias:
   • For a property editor: use the schema alias (e.g., 'Umbraco.ColorPicker')
   • For a domain type: use Umb.ValueType.{Entity}.{Shape} (e.g., 'Umb.ValueType.UserGroup.References')
4. TypeScript type — the type of the raw value (e.g., string, boolean, UmbReferenceByUnique[])

Step 1: Create the constant file

File: {package-path}/value-type/constants.ts

export const UMB_{FEATURE}_VALUE_TYPE = '{value-type-key}' as const;

declare global {
	interface UmbValueTypeMap {
		[UMB_{FEATURE}_VALUE_TYPE]: {TValue};
	}
}

Rules:

• The string value is always as const.
• The declare global block is in the same file as the constant.
• One constant per file — do not group multiple value types.

Property editor example

import type { UmbColorPickerPropertyEditorValue } from '../types.js';

export const UMB_COLOR_PICKER_VALUE_TYPE = 'Umbraco.ColorPicker' as const;

declare global {
	interface UmbValueTypeMap {
		[UMB_COLOR_PICKER_VALUE_TYPE]: UmbColorPickerPropertyEditorValue;
	}
}

Domain type example

import type { UmbReferenceByUnique } from '@umbraco-cms/backoffice/models';

export const UMB_USER_GROUP_REFERENCES_VALUE_TYPE = 'Umb.ValueType.UserGroup.References' as const;

declare global {
	interface UmbValueTypeMap {
		[UMB_USER_GROUP_REFERENCES_VALUE_TYPE]: UmbReferenceByUnique[];
	}
}

Step 2: Export from the package index

Add to the package index.ts:

export * from './value-type/constants.js';

Checklist

• Constant declared with as const
• declare global block extends UmbValueTypeMap in the same file
• Key follows naming convention (schema alias for property editors, Umb.ValueType.{Entity}.{Shape} for domain types)
• TypeScript type is the correct raw value type
• One constant per file
• Constant exported from package index.ts
• Compiles: npm run compile