Website Builder > Page Settings

Page Settings

Learn how to add custom settings groups and modify existing ones in the Website Builder page settings drawer.

WHAT YOU'LL LEARN

how to add a new settings group (tab) to the page settings drawer
how to modify an existing settings group with additional fields
where to store custom page data (doc.extensions)

Overview

The page settings drawer in the Website Builder editor contains tabbed groups — General, SEO, Social, and Schema. Each group defines a form with fields that map to and from the page document.

You can add entirely new tabs using the PageSettingsGroup abstraction, or inject fields into existing tabs using PageSettingsGroupModifier. Both are available from webiny/admin/website-builder/page/editor.

IMPORTANT

Store all custom data in doc.extensions — never write to doc.properties, which is reserved for built-in system properties (title, path, snippet, image, tags, seo, social). Writing custom fields into doc.properties risks naming collisions with future Webiny updates.

Add a 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
`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
`buildForm(form)`	method	Define fields and layout
`mapToForm(doc)`	method	Read from the page document to populate the form
`mapFromForm(formData, doc)`	method	Write form values back to the page document

extensions/myPageSettings/PublishingSettingsGroup.ts

Data Mapping

The mapToForm and mapFromForm methods bridge the page document and the settings form:

mapToForm(doc) — reads from doc.extensions and returns an object whose keys match the field names defined in buildForm. Provide sensible defaults for missing values.
mapFromForm(formData, doc) — receives form values and writes them back to doc.extensions. Always namespace your data under your group name (e.g., doc.extensions.publishing) to avoid collisions with other extensions.

Modify an Existing Settings Group

A modifier injects fields into an existing tab without replacing it. Implement PageSettingsGroupModifier.Interface:

Member	Type	Description
`group`	`string`	Name of the target group to modify
`modifyForm(form)`	method	Add fields and layout entries to the existing group
`mapToForm(doc)`	method (optional)	Supply values for the new fields
`mapFromForm(formData, doc)`	method (optional)	Persist the new field values

The built-in group names are: "general", "seo", "social", "schema".

extensions/myPageSettings/GeneralSettingsModifier.ts

Layout Positioning

Use .after("existingFieldName") to position new fields relative to built-in fields. The built-in field names for each group:

general: title, path, snippet, image, tags
seo: title, description, metaTags, canonicalUrl, noIndex, noFollow
social: title, description, image, metaTags
schema: structuredSchema

Register the Feature

Wire the implementations together using createFeature and RegisterFeature from webiny/admin:

extensions/myPageSettings/index.tsx

container.register(PublishingSettingsGroup) — adds a new tab to the settings drawer
container.register(GeneralSettingsModifier) — injects fields into the existing General tab; omit this line if you don’t need to modify existing groups

Then register the extension in webiny.config.tsx:

webiny.config.tsx

The Page Document Model

The doc parameter in mapToForm / mapFromForm has three top-level namespaces:

doc.properties and doc.metadata are managed by the system. Always read/write your custom data via doc.extensions, namespaced under your group name (e.g., doc.extensions.publishing, doc.extensions.analytics).