Extending the Website Builder page settings with custom settings groups and modifiers. Use this skill when the developer wants to add a new tab/group to the page settings drawer (e.g., Publishing, Analytics, Access Control), or modify an existing settings group (e.g., add fields to General or SEO). Covers PageSettingsGroup, PageSettingsGroupModifier, and the doc.extensions data model. For field types, renderers, and layout details, see the webiny-form-model skill.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Extending the Website Builder page settings with custom settings groups and modifiers. Use this skill when the developer wants to add a new tab/group to the page settings drawer (e.g., Publishing, Analytics, Access Control), or modify an existing settings group (e.g., add fields to General or SEO). Covers PageSettingsGroup, PageSettingsGroupModifier, and the doc.extensions data model. For field types, renderers, and layout details, see the webiny-form-model skill.
Page Settings Extensions
TL;DR
Page settings extensions let you add new tabs to the page settings drawer or inject fields into existing tabs. Create a class implementing PageSettingsGroup.Interface for a new tab, or PageSettingsGroupModifier.Interface to extend an existing one. Register both via createFeature() and <RegisterFeature>. Always store custom data in doc.extensions — never write to doc.properties, which is reserved for built-in system properties.
YOU MUST include the full file path with the .tsx extension in every src prop. For example, use src={"/extensions/myPageSettings/index.tsx"}, NOT src={"/extensions/myPageSettings/index"}. Omitting the file extension will cause a build failure.
For field types, renderers, layout, validation, and all other form builder APIs, refer to the webiny-form-model skill.
Important: Where to Store Data
Use doc.extensions for all custom data. The doc.properties object holds built-in system properties (title, path, snippet, image, tags, seo, social). Writing custom fields into doc.properties risks naming collisions with future Webiny updates and can corrupt system behavior. Always namespace your data under .
doc.extensions.<yourGroupName>
// CORRECT — custom data in doc.extensionsmapFromForm(formData, doc) {
doc.extensions.mySettings = doc.extensions.mySettings ?? {};
doc.extensions.mySettings.myField = formData.myField;
}
// WRONG — never write custom data into doc.propertiesmapFromForm(formData, doc) {
doc.properties.myField = formData.myField; // DON'T DO THIS
}
Adding a New Settings Group
A new settings group appears as its own tab in the page settings drawer. Implement PageSettingsGroup.Interface with these members:
Member
Type
Description
name
string
Unique group identifier (used as form field namespace)
label
string
Tab label shown in the UI
description
string (optional)
Description shown below the tab label
icon
{ type: "icon", name: string } (optional)
FontAwesome icon for the tab (e.g., "fas/calendar-alt")
When modifying an existing group, use .after("existingFieldName") to position your new fields relative to built-in fields. The built-in field names for each group:
The doc parameter in mapToForm / mapFromForm has three top-level namespaces:
interfaceIPageDocument {
properties: { ... }; // SYSTEM — title, path, snippet, seo, social, etc.metadata: { ... }; // SYSTEM — document metadataextensions: { ... }; // YOUR DATA — use this for all custom fields
}
Reminder: doc.properties and doc.metadata are managed by the system. Always read/write your custom data via doc.extensions. Namespace it under your group name to avoid collisions with other extensions (e.g., doc.extensions.publishing, doc.extensions.analytics).
Related Skills
webiny-form-model — Field types, renderers, layout, validation, conditional rules, computed fields, and dynamic zones
