Restrict widgets

Every place widgets go takes the same allowlist. Write it on a blocks() field, on an editable page zone or on a content zone, and the editor only offers what fits. Where you write it decides whether the API enforces it.

The list formatCopy Anchor Link

An allowlist is "*" or an array mixing exact ids and plugin wildcards:

'*' // every installed widget
['core:*', 'newsroom:*'] // every widget of two plugins
['core:hero', 'newsroom:callout'] // exactly these two

A plugin wildcard is the useful middle. Installing another plugin does not silently widen what a page may contain, while a new widget in a plugin you already trust appears automatically. An Area needs no entry; the widgets inside it are checked against the same list.

Where it is enforcedCopy Anchor Link

In the visual editor, all three behave the same. Add widget on a zone lists only what the zone accepts, and a zone turns red and refuses a widget dragged onto it that it does not accept. Only the first two are also checked on the server. A custom editor host that saves a standalone zone must check the list in its own save route.

On a blocks() fieldCopy Anchor Link

content: field.blocks({
  allowed: PAGE_BLOCKS_ALLOWED,
  max: 50,
}),

The default is "*". A write holding a widget the field does not allow answers 400 with Block "core:cta" is not allowed in this field., and nothing is stored.

On an editable pageCopy Anchor Link

Each zone declares its list once, in defineEditablePage, and every ContentZone with that id inherits it:

zones: {
  'before-profile': { allowed: PAGE_BLOCKS_ALLOWED, max: 20 },
  sidebar: { allowed: PAGE_SIDEBAR_BLOCKS_ALLOWED, max: 20 },
},

The server reads the list from the registered page, never from the request, so no request can sneak a widget into a zone that refuses it. Props on the page's ContentZone can narrow the declaration but never widen it:

On a zoneCopy Anchor Link

A standalone ContentZone describes what belongs in a place; it does not guard storage. While rendering, its validate mode decides what happens to a stored widget the list does not allow:

Use "always" on a page that renders widgets the API never checked, such as a live import. See Validation for the rest of what the renderer checks.

Share one listCopy Anchor Link

When a field and the page that renders it should accept the same widgets, put the list in a module of its own and import it from both. The newsroom plugin keeps its lists in src/content/page-blocks.ts:

export const PAGE_BLOCKS_ALLOWED = [
  'core:*',
  'newsroom:callout',
  'newsroom:features',
] as const

export const PAGE_SIDEBAR_BLOCKS_ALLOWED = ['core:text'] as const

page.ts passes PAGE_BLOCKS_ALLOWED to the field, and pages/site-page.tsx passes the same constant to its zone as allowedBlocks. Import the array, not the content type. A page that imports a content type definition pulls the whole schema builder into its bundle to read one list.

Check the resultCopy Anchor Link

Sign in as an administrator, open /newsroom/zones and choose Edit widgets from the user menu. Add widget on the sidebar zone lists only Text, because the sidebar allows core:text alone; drag the callout from another zone onto the sidebar and the sidebar turns red and refuses it.

RelatedCopy Anchor Link

• Editable pages: declare a page's zones and their lists.
• Saving layouts: every refusal a layout save can answer.