How to implement a custom CMS field type that integrates with the model builder's fluent API. Covers extending DataFieldBuilder, composing validator interfaces, creating a FieldTypeFactory, registering via DI, and module augmentation for TypeScript autocomplete on the fields() registry.
A custom field type is a class that extends DataFieldBuilder<"yourType">, paired with a factory class implementing FieldType.Factory. Register the factory with container.register(YourFieldType). Add a module augmentation on "webiny/api/cms/model" so the fields registry method gets TypeScript autocomplete.
Use a custom field type when:
text, number, boolean, datetime, file, ref, object, richText, longText, json, dynamicZone)fields.slug(), fields.color()) in implementationsModelFactoryA custom field type consists of three parts:
DataFieldBuilder<"type"> plus FieldTypeValidator.* typesthis.validation() for each validatorFieldType.Factory, creates builder instancesAs a standalone extension (not part of a larger feature), the directory layout is:
extensions/
└── SlugFieldType/
├── SlugFieldType.ts # builder interface, builder class, factory class
└── feature.ts # createFeature — registers the factory into the DI container
feature.ts:
// extensions/SlugFieldType/feature.ts
import { createFeature } from "webiny/api";
import { SlugFieldType } from "./SlugFieldType.js";
export const SlugFieldTypeFeature = createFeature({
name: "SlugFieldType",
register(container) {
container.register(SlugFieldType);
}
});
Register in the API entry point:
// api/Extension.ts
import { createFeature } from "webiny/api";
import { SlugFieldTypeFeature } from "~/extensions/SlugFieldType/feature.js";
export const Extension = createFeature({
name: "MyExtension",
register(container) {
SlugFieldTypeFeature.register(container);
}
});
// extensions/SlugFieldType/SlugFieldType.ts
import { DataFieldBuilder, FieldType } from "webiny/api/cms/model";
import type { FieldTypeValidator } from "webiny/api/cms/model";
// 1. Builder interface — extends DataFieldBuilder + desired FieldTypeValidator types
export interface ISlugFieldBuilder
extends
DataFieldBuilder<"slug">,
FieldTypeValidator.Required,
FieldTypeValidator.Pattern,
FieldTypeValidator.Unique {}
// 2. Module augmentation — adds fields.slug() to the registry
declare module "webiny/api/cms/model" {
interface IFieldBuilderRegistry {
slug(): ISlugFieldBuilder;
}
interface IFieldRendererRegistry {
myCustomRenderer: {
fieldType: "text" | "number";
settings: undefined;
};
}
}
// 3. Builder class — implements each validator method via this.validation()
class SlugFieldBuilder extends DataFieldBuilder<"slug"> implements ISlugFieldBuilder {
constructor() {
super("slug");
}
required(message?: string): this {
return this.validation({
name: "required",
message: message || "Value is required.",
settings: {}
});
}
pattern(regex: string, flags = "", message?: string): this {
return this.validation({
name: "pattern",
message: message || "Invalid value.",
settings: { preset: "custom", regex, flags }
});
}
unique(message?: string): this {
return this.validation({
name: "unique",
message: message || "Value must be unique.",
settings: {}
});
}
}
// 4. Factory class — implements FieldType.Factory
class SlugFieldTypeFactory implements FieldType.Factory {
readonly type = "slug";
create(): ISlugFieldBuilder {
return new SlugFieldBuilder();
}
}
// 5. Export as a FieldType implementation
export const SlugFieldType = FieldType.createImplementation({
implementation: SlugFieldTypeFactory,
dependencies: []
});
After registration, fields.slug() is available in any ModelFactory implementation:
import { ModelFactory } from "webiny/api/cms/model";
class ProductModelImpl implements ModelFactory.Interface {
async execute(builder: ModelFactory.Builder) {
return [
builder
.public({ modelId: "product", name: "Product", group: "ungrouped" })
.fields(fields => ({
name: fields.text().label("Name").required(),
slug: fields
.slug()
.label("Slug")
.required("Slug is required.")
.unique()
.pattern("^[a-z0-9-]+$", "", "Only lowercase letters, numbers, and hyphens.")
}))
.layout([["name", "slug"]])
.titleFieldId("name")
.singularApiName("Product")
.pluralApiName("Products")
];
}
}
All methods return this for chaining.
| Method | Description |
|---|---|
label(text) | Field label shown in the Admin editor |
help(text) | Help text shown below the field |
description(text) | Field description |
fieldId(id) | Override the auto-derived field ID |
storageId(id) | Override the storage identifier |
placeholder(text) | Placeholder text for the input |
defaultValue(value) | Default value for new entries |
list() | Make the field accept multiple values (array) |
listMinLength(n, msg?) | Minimum number of list items |
listMaxLength(n, msg?) | Maximum number of list items |
tags(tags) | Arbitrary tags for filtering/querying |
renderer(name, settings?) | Set the Admin UI renderer |
settings(settings) | Set arbitrary field settings |
| Method | Description |
|---|---|
this.validation(rule) | Append a CmsModelFieldValidation to the field's validation array |
this.listValidation(rule) | Append a CmsModelFieldValidation to the list validation array |
A CmsModelFieldValidation has the shape:
{
name: string; // validator name (e.g., "required", "minLength", "pattern")
message: string; // error message shown to the user
settings: Record<string, any>; // validator-specific config
}
Import via import type { FieldTypeValidator } from "webiny/api/cms/model" and extend your builder interface with them. Each type adds one method to your interface:
| Type | Method signature |
|---|---|
FieldTypeValidator.Required | required(message?) |
FieldTypeValidator.Unique | unique(message?) |
FieldTypeValidator.MinLength | minLength(value, message?) |
FieldTypeValidator.MaxLength | maxLength(value, message?) |
FieldTypeValidator.Pattern | pattern(regex, flags?, message?) |
FieldTypeValidator.Email | email(message?) |
FieldTypeValidator.Url | url(message?) |
FieldTypeValidator.LowerCase | lowerCase(message?) |
FieldTypeValidator.UpperCase | upperCase(message?) |
FieldTypeValidator.LowerCaseSpace | lowerCaseSpace(message?) |
FieldTypeValidator.UpperCaseSpace | upperCaseSpace(message?) |
FieldTypeValidator.Gte | gte(value, message?) |
FieldTypeValidator.Lte | lte(value, message?) |
FieldTypeValidator.DateGte | dateGte(value, message?) |
FieldTypeValidator.DateLte | dateLte(value, message?) |
FieldTypeValidator.ListMinLength | listMinLength(value, message?) |
FieldTypeValidator.ListMaxLength | listMaxLength(value, message?) |
When implementing a validator method in the builder class, call this.validation() with the appropriate name and settings. For ListMinLength/ListMaxLength, call this.listValidation() instead. The settings shapes:
| Validator | name | settings |
|---|---|---|
| Required, Unique | "required" / "unique" | {} |
| MinLength, MaxLength | "minLength" / "maxLength" | { value: String(n) } |
| Gte, Lte | "gte" / "lte" | { value: String(n) } |
| DateGte, DateLte | "dateGte" / "dateLte" | { value } |
| Pattern | "pattern" | { preset: "custom", regex, flags } |
"pattern" | { preset: "email", regex: null, flags: null } | |
| Url | "pattern" | { preset: "url", regex: null, flags: null } |
| LowerCase / UpperCase / etc. | "pattern" | { preset: "lowerCase" / "upperCase" / etc., regex: null, flags: null } |
type string must be unique — the factory's readonly type must not collide with any built-in type (text, number, boolean, datetime, file, ref, object, richText, longText, json, dynamicZone) or other custom types."webiny/api/cms/model" using namespace FieldBuilderRegistry { interface Interface { yourType(): IYourFieldBuilder; } }.validation() is protected — never call it from outside the builder class. Expose validators as named methods on the interface (e.g., required(), minLength()).dependencies: [] — field type factories have no DI dependencies; always pass an empty array.FieldType implementations before FieldBuilderRegistry is resolved (i.e., in the same register() call or before it runs). The registry collects all FieldType instances at construction time.ModelFactory, FieldType, DataFieldBuildercreateImplementation pattern and DI scoping