Document schema and blocks

Nucleo 0.2+Free~43 min readUpdated October 31, 2026

Every page is a JSON document with a tree of nodes: here you find its structure, the validation rules and the available blocks.

On this page

01Overview

Every page, layout, reusable section or popup is a JSON document with a tree of nodes. Every node has a type that refers to a registered block. A block is a folder in nucleo/blocks/ with a block.nucleo.json manifest and a PHP renderer. The manifest declares the properties (content, settings), the style groups, and the allowed children and parents.

When the document is saved, it goes through two phases:

Normalization

Nucleo completes the document, expands the sections and resolves the internal links.

Validation

First the JSON schema is checked, then the rules of the manifests and the checks specific to some blocks.

If there is at least one error, the save fails with the code invalid_document and the list of errors.

Compilation, dynamic slots, CSS and reusable sections are described on the Compiler and runtime page.

All blocks in this chapter are Free.

Blocks have no permissions of their own. The permissions of the ability or command that saves the document apply, see Write abilities and WP-CLI commands.

WooCommerce blocks (woo/*) are registered with the nucleo/register_blocks action and are described on the Integrations page.

02JSON document

Top-level keys

What it does: defines the shape of the document. additionalProperties: false: every other key is an error.

How to use: minimal example:

{
  "schema": 1,
  "kind": "page",
  "root": { "id": "a1", "type": "nc/section", "children": [] }
}

Parameters:

Name	Type	Allowed values	Default	Note
`schema`	integer	`>= 1`	`1`	Required in the schema. If missing, the normalizer sets it to `1` before validation.
`kind`	string	`page`, `layout`, `section`, `popup`	—	Required.
`root`	node	see Node	—	Required. Root of the tree.
`meta`	object	key `seo` defined; other keys free	—	See `meta.seo`.
`params`	object	name `^[a-z][a-z0-9_]{0,31}$` → `{type, label?, required?}`	—	Parameters of a reusable section. `type`: `text`, `html`, `image`, `link`, `color`, `boolean`, `list`.
`blocks`	object	block type → integer `>= 1`	—	Version of each block the document was written with. It is used by the migrator.

Permissions: those of the document save.

Edition: Free

Known limits:

The schema describes params as valid only for kind section, but the validator does not enforce this rule.
propertyNames is not applied by the internal validator (see JSON Schema subset). The section expansion checks the parameter names (invalid parameter name). The names in blocks are not checked.
A list parameter accepts at most 30 strings.

Node

What it does: describes a block in the tree. content, settings and style are separate: content holds the translatable texts, settings the behavior, style the appearance.

How to use: node example:

{ "id": "a2", "type": "nc/heading",
  "content": { "text": "Tax consulting" },
  "settings": { "level": 1 },
  "style": { "fontSize": { "base": "$text.3xl", "lg": "$text.5xl" } } }

Parameters:

Name	Type	Allowed values	Default	Note
`id`	string	`^[a-z0-9]{1,12}$`	—	Required. Unique in the document.
`type`	string	`^[a-z][a-z0-9-]/[a-z][a-z0-9-]$`, registered block	—	Required.
`content`	object	keys declared in `content` of the manifest	—
`settings`	object	keys declared in `settings` of the manifest	manifest default	The normalizer adds the missing defaults.
`style`	object	style keys, `parts`, `custom`	—	See Style values.
`visibility`	object	`breakpoints`, `when`	—	See `visibility`.
`bind`	object	`content.<name>` or `settings.<name>` → `{source, field, fallback?}`	—	See `bind`.
`children`	array of nodes	according to `children` of the manifest	—
`ref`	string	`^(section):[0-9]+$`	—	Legacy form: reference by id to a section. Excludes `children`.
`guide`	object	`{ "distinct": string 1–200 characters, not only spaces }`	—	Note for `nucleo guide`: the block is intentionally similar to another one and does not count among the repetitions of rule R1.5.

Permissions: those of the document save.

Edition: Free

Known limits:

ref and children together are a schema error.
An invalid id produces a single error with the correct suggestion: lowercase letters and digits, truncated to 12 characters (use "abc123").
A duplicate id is reported on the second occurrence (duplicate id).

`meta.seo`

What it does: sets the title and SEO meta of the page when no SEO plugin is active.

How to use: "meta": { "seo": { "title": "...", "description": "...", "noindex": false } }. The use on the page is described on the Integrations page.

Parameters:

Name	Type	Allowed values	Default	Note
`title`	string	max 70 characters	—
`description`	string	max 170 characters	—
`image`	string	`format: uri`	—	The format is not checked (see limits).
`noindex`	boolean	—	—
`breadcrumbs`	boolean	—	—	`false`: no automatic `BreadcrumbList` on the page.
`schema`	array of objects	max 10; each object has `@type` `^[A-Z][A-Za-z]{2,60}$`	—	schema.org nodes of the page. The value `"@business"` refers to the company of the site.

Permissions: those of the document save.

Edition: Free

Known limits: seo does not accept other keys besides those listed. The validator ignores format.

Style values

What it does: each key of style is a CSS property in camelCase with a simple value or an object per breakpoint.

How to use: "padding": "$space.4" or "padding": { "base": "$space.4", "md": "$space.6" }. The references $group.key are tokens, see the Design tokens page.

Parameters:

Name	Type	Allowed values	Default	Note
`<key>`	string, number, or object	object with at least one key among `base`, `md`, `lg`, `xl`	—	The key must belong to a `supports.style` group of the block.
`<key>Hover`, `<key>Current`	as above	—	—	States. Only for `color`, `background`, `border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `boxShadow`, `opacity`, `filter`, `fontWeight`, `textDecoration`.
`parts`	object	name of the part declared by the block → style keys	—	Groups allowed in a part: `size`, `spacing`, `typography`, `color`, `border`, `effects`, `layout`, `motion`.
`custom`	object	selector starting with `&` → CSS property → string or number	—	Free CSS for what the keys do not cover.

Permissions: those of the document save.

Edition: Free

Known limits:

A string value cannot contain ;, {, }, <, >, \, /*, */ or control characters. It cannot contain url(, expression(, @import, image-set(, image(, cross-fade(, element(, src( or javascript:. Parentheses and quotes must be closed. An empty string is not allowed.
A cited token that does not exist in the site tokens produces unknown token.
Selector of custom: ^&[a-zA-Z0-9_ .:>#()+~*,="'\[\]-]*$. Property of custom: ^-{0,2}[a-z][a-z0-9-]{0,60}$.
Keys with a closed list (position, overflow*, textDecoration, textTransform, whiteSpace, fontStyle, alignSelf, justifySelf and others) reject other values. zIndex accepts an integer between -9999 and 9999.
The values of motion have their own validation.

`visibility`

What it does: hides the node by breakpoint (CSS) or by condition (dynamic slot).

How to use: "visibility": { "breakpoints": { "base": false, "lg": true }, "when": [{ "is": "logged_in" }] }. The effect at runtime is described on the Compiler and runtime page.

Parameters:

Name	Type	Allowed values	Default	Note
`breakpoints`	object	`base`, `md`, `lg`, `xl` → boolean	—
`when[].is`	string	`logged_in`, `logged_out`, `role:<slug>` (`[a-z0-9_-]+`), `filled`, `empty`	—	Required.
`when[].source`	string	`post`, `nucleo`, `item`, `acf`, `metabox`, `jetengine`, `author`, `term`, `site`	—	Required with `filled` and `empty`.
`when[].field`	string	not empty	—	Required with `filled` and `empty`.

Permissions: those of the document save.

Edition: Free

Known limits: in the cards of nc/query, nc/collection and in the rows of nc/repeater only filled and empty are allowed (code card_block_not_allowed).

`bind`

What it does: connects a property of the node to a dynamic value.

How to use: "bind": { "content.text": { "source": "post", "field": "title", "fallback": "—" } }. Sources and resolution are described on the Dynamic data page.

Parameters:

Name	Type	Allowed values	Default	Note
key	string	`content.<name>` or `settings.<name>` declared by the block	—	A key not declared produces `bind key not declared in the block`.
`source`	string	`post`, `term`, `author`, `site`, `nucleo`, `acf`, `metabox`, `jetengine`, `woo`, `user`, `query`, `param`, `item`	—	Required.
`field`	string	not empty	—	Required.
`fallback`	string	—	—

Permissions: those of the document save.

Edition: Free

Known limits:

The validator accepts every property declared by the block. It ignores supports.bind of the manifest.
Inside a reusable section, the keys style.<name>, visible and repeat are handled by the expansion and removed before validation (see Compiler and runtime).
In the cards, the sources user and query are not allowed (card_block_not_allowed).

03Validation

Order of checks

What it does: validation returns the list of all errors. It does not stop at the first one.

How to use: the save and nucleo/doc-validate use it. For each node, in this order:

JSON schema of the document.
Registered type. If missing, the error lists all registered types in allowed.
id: rule and uniqueness.
Allowed parent (parents of the manifest).
content and settings: declared keys, type and constraints of each property, required fields, keys of the elements with item.
style: supported group, allowed value, safe CSS, existing token. Then style.parts and style.custom.
bind: declared key.
Checks specific to the block: nc/query, nc/collection, nc/repeater, nc/native-form, nc/embed.
nc/icon: icon name.
URLs in settings.href and content.src.
visibility.when.
Allowed children (children of the manifest), then recursion into the children.

Parameters: the normalized document.

Permissions: those of the calling ability or command.

Edition: Free

Known limits:

Property types of the manifests that are not JSON types (inline-rich-text, rich-text) are validated as string.
Errors with the same path and the same message appear only once.
Without tokens the token check is skipped. The site validator always passes the site tokens.
Errors on nodes that come from a section point to the nc/section-ref of the document.

Error format

What it does: every error says where, what and how to fix it.

How to use: every error has this shape:

{ "path": "/root/children/0/settings/level", "message": "...", "got": 7,
  "allowed": [1, 2, 3, 4, 5, 6], "fix": "...", "code": "card_missing", "guide": "R3.3" }

Parameters:

Name	Type	Allowed values	Default	Note
`path`	string	JSON Pointer	—	Always present.
`message`	string	—	—	Always present, translated.
`got`	any	—	—	Absent if null.
`allowed`	list	—	—	Absent if empty.
`fix`	string	—	—	Suggested fix.
`code`	string	see Error codes	—	Absent for schema errors.
`guide`	string	`R3.3`, `R4.3`	—	Rule of `nucleo guide` linked to the code.

Permissions: —

Edition: Free

Known limits: on save, the result is invalid_document with the message Invalid document.. If there are style_group_unsupported errors, the message lists them all in one sentence, with the place to move each key.

Error codes

What it does: stable codes for agents. The other errors have only message.

How to use: read code in the errors list of the result.

Parameters:

Code	Block	When
`style_group_unsupported`	all	The style key belongs to a group that the block does not have. `fix` suggests the children that have the group, or a `doc-patch` `wrap` in `nc/container`, or the blocks that have the group.
`card_missing`	`nc/query`	More than one child.
`card_missing`	`nc/repeater`	Number of children different from 1.
`card_missing`	`nc/collection`	Number of `nc/collection-card` different from 1, or a card with more than one child.
`card_block_not_allowed`	cards of `nc/query`, `nc/collection`, `nc/repeater`	Block not allowed in the card, source `user` or `query`, visitor condition, `nc/repeater` nested in a row.
`field_missing`	`nc/repeater`	`settings.field` empty.
`card_term_source`	`nc/collection`	Card of a `terms` collection that reads the post or sources other than `term`.
`unknown_component`	`nc/collection`, `nc/native-form`	Source or action `component` not registered.
`unknown_post_type`	`nc/collection`, `nc/native-form`	Content type not allowed or not in the model.
`unknown_taxonomy`	`nc/collection`	Taxonomy not public, or not linked to the content type.
`unknown_term`	`nc/collection`	`settings.parent` is not a term of the taxonomy.
`unknown_field`	`nc/collection`, `nc/native-form`	Field that does not exist or of a type not allowed.
`terms_no_filters`	`nc/collection`	`terms` collection with filters or sorting.
`duplicate_key`	`nc/collection`	Filter or sort key repeated, or `sort` or `page`.
`bad_ui`	`nc/collection`	`ui` not allowed for the filter type.
`duplicate_field`	`nc/native-form`	Field name repeated.
`bad_options`	`nc/native-form`	`select`, `radio` or `checkboxes` field without options.
`bad_step`	`nc/native-form`	Field `step` outside the steps of the form.
`otp_first`	`nc/native-form`	`otp` action not in first position, or field not of type `email`.
`otp_step`	`nc/native-form`	`step` of the `otp` action not consistent with the steps.
`unverified_recipient`	`nc/native-form`	`email` action with `to: "field:<name>"` without `otp` on the same field.
`bad_status`	`nc/native-form`	`create-post` with a status other than `draft` or `pending`.
`unsafe_url`	`nc/native-form`, `nc/embed`	`webhook` with a URL that is not `https://`; `settings.url` of `nc/embed` that is not `https://`.
`invalid_url`	`nc/embed`	YouTube or Vimeo address without a valid video id.

Permissions: —

Edition: Free

Known limits: only these codes link to a rule of nucleo guide: card_missing and card_block_not_allowed (R3.3), and component_code (R4.3).

URL check

What it does: rejects dangerous URLs in settings.href and content.src of every node.

How to use: automatic. The check accepts http, https, mailto, tel and the relative ones that start with / (not //), # or ?.

Parameters: none.

Permissions: —

Edition: Free

Known limits:

settings.href also accepts an internal reference: home, page:<slug>, post:<slug>, <post-type>:<slug>, term:<taxonomy>/<slug>. Resolution is described on the Compiler and runtime page.
The check covers only the two top-level keys. It does not cover settings.parent.href of nc/breadcrumbs, content.poster of nc/video, settings.redirect of nc/native-form, or settings.url of nc/embed, which the block checks itself. The renderers of nc/video and nc/button filter their own values.

JSON Schema subset

What it does: the internal validator, without dependencies, checks the document and the properties of the manifests.

How to use: internal.

Parameters: keywords applied: type, enum, const, $ref (only #/$defs/...), allOf, anyOf, oneOf, not, properties, patternProperties, additionalProperties, required, minProperties, items, minItems, maxItems, minLength, maxLength, pattern, minimum, maximum.

Permissions: —

Edition: Free

Known limits:

The other keywords are ignored, among them format, propertyNames, uniqueItems.
min and max are also ignored, used by the manifest of nc/slider. Only the renderer applies the limits of perView, autoplay and speed.
An empty array is valid both as an array and as an object.

04Normalization, versions and migrations

Normalizer

What it does: completes the document before validation and compilation.

How to use: the normalizer runs these steps, in this order:

A missing schema becomes 1.
Block migrations.
Defaults of the settings from the manifest, for every node with a registered type. Explicit values stay.
Node with ref: "section:N": becomes the root of section N. The internal ids get the prefix g<N>, truncated to 12 characters. The node keeps its own id. The referenced document does not follow other ref.

Parameters: none.

Permissions: —

Edition: Free

Known limits:

The defaults apply only to settings, not to content.
An unresolved ref stays as it is.

Warning

The save stores the raw document, not the normalized one.

Schema version

What it does: schema is the version of the document format.

How to use: write "schema": 1.

Parameters: none.

Permissions: —

Edition: Free

Known limits: the list of document migrations is empty. At version 0.2.0 there are no document migrations.

Block migrations

What it does: brings every node to the current version of its block, with operations declared in the manifest.

How to use: in the manifest, migrations maps the arrival version to a list of operations:

"migrations": { "2": [ { "op": "rename", "from": "settings.size", "to": "settings.level" } ] }

Parameters:

Name	Type	Allowed values	Default	Note
`op: rename`	`from`, `to`	dotted path `^[a-zA-Z_][a-zA-Z0-9_-](\.…)$`	—	Only if `from` exists and `to` does not.
`op: remove`	`path`	dotted path	—
`op: set`	`path`, `value`	dotted path	—	Only if `path` does not exist.

Permissions: —

Edition: Free

Known limits:

The migrations applied are those with a version greater than the one saved in blocks and less than or equal to the current one, in numeric order.
A document without the block version in blocks does not migrate: the system records only the current version.
All 41 blocks are at version 1 and have migrations empty or absent.

Compact format

What it does: reduces the document for an agent.

How to use: used by nucleo/doc-get.

Parameters:

Name	Type	Allowed values	Default	Note
`nodeId`	string	id of a node	null	Returns only that subtree. Missing id: `not_found` error.
`depth`	integer	`>= 0`	null	Nodes at depth `>= depth` lose `children` and get `childCount`. Negative: `invalid_op` error.

Permissions: those of the ability.

Edition: Free

Known limits: removes content, settings, style, visibility, bind when empty, and the settings equal to the default. It does not change the tokens.

Document patch

What it does: describes the operations of nucleo/doc-patch.

How to use: an array of semantic operations by id (insert, move, remove, set, duplicate, wrap) or JSON Patch RFC 6902 by path (add, replace, test, remove, move, copy).

Parameters: see the Write abilities chapter.

Permissions: those of the ability.

Edition: Free

Known limits: baseRevision sits in the patch container, not in the array.

05Block manifests

Manifest fields

What it does: Nucleo reads the block.nucleo.json manifest of every folder in nucleo/blocks/. An invalid manifest blocks the loading with an error that names the file.

How to use: one folder per block with block.nucleo.json, style.css and an optional view.js. The renderers of the nc/* blocks are included in the plugin.

Parameters:

Name	Type	Allowed values	Default	Note
`name`	string	`^[a-z][a-z0-9-]/[a-z][a-z0-9-]$`	—	Required. Unique: a duplicate is an error.
`version`	integer	`>= 1`	—	Required.
`title`	string	not empty	—	Required.
`category`	string	—	`general`
`description`, `aiHints`	string	—	`""`	`aiHints` are the instructions for the agent returned by `nucleo/catalog-get`.
`content`, `settings`	object	name → `{type, translatable?, required?, default?, item?, …}`	`{}`	JSON Schema subset. `item` describes the keys of each element of an array.
`supports.style`	list	style groups	—	The registry adds the base groups. See Style groups.
`supports.styleExclude`	list	`size`, `spacing`, `typography`, `color`, `border`, `motion`	—	Base groups that the block does not receive.
`supports.responsive`, `supports.visibility`, `supports.bind`	—	—	—	Informational: `nucleo/catalog-get` returns them, the validator does not read them.
`parts`	object	name `^[a-z][a-zA-Z0-9]{0,30}$` → selector inside the node	`{}`	Styleable parts for `style.parts`.
`children`	boolean or list of types	—	`false`	`true`: any child. List: only those types.
`parents`	null or list of types	—	`null`	`null`: any parent.
`assets.style`, `assets.script`	string or null	path relative to the folder	—
`assets.strategy`	string	`eager`, `visible`, `interaction`, `idle`	`eager`	Loading of the script, see the Optimizer and assets page.
`semantics`	object	`heading`, `image`, `link`, `landmark`, `text`, `embed`	`{}`	Used by the quality engine. `landmark` takes `tagFrom` (field with the tag) or `tag` (fixed tag), and `ifFrom` (field that must have a value).
`renderer`	string	class that implements `Nucleo\Blocks\Renderer`	`""`	If the class does not exist, Nucleo loads `Renderer.php` from the block folder.
`deps`	list	`^[a-z_]+(?::[A-Za-z0-9_.{}-]+)*$`	`[]`	Invalidation keys, for example `menu:{settings.menu}`.
`migrations`	object	see Block migrations	—

Permissions: —

Edition: Free

Known limits: the error Renderer "<class>" not found for block <type> appears only at the first compilation of the block, not at loading.

Style groups

What it does: every style key belongs to a group. A block accepts only the keys of its groups.

How to use: every block receives the base groups size, spacing, typography, color, border, motion, except supports.styleExclude. The groups declared in supports.style are added. The list of each block is in its section. The CSS output is described on the Compiler and runtime page.

Parameters:

Group	Keys
`spacing`	`padding`, `margin`, `gap`
`size`	`width`, `maxWidth`, `minWidth`, `maxHeight`, `minHeight`, `height`, `aspectRatio`
`color`	`color`, `background`, `accentColor`
`typography`	`fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFamily`, `fontStyle`, `textAlign`, `textDecoration`, `textTransform`, `whiteSpace`
`layout`	`display`, `columns`, `direction`, `wrap`, `justify`, `align`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `alignSelf`, `justifySelf`
`border`	`border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderRadius`, `boxShadow`
`effects`	`opacity`, `objectFit`, `filter`, `transform`
`position`	`position`, `top`, `right`, `bottom`, `left`, `inset`, `zIndex`, `scrollMarginTop`, `overflow`, `overflowX`, `overflowY`
`motion`	`animation`, `animationDuration`, `animationDelay`, `transition`
`menu`	`itemColor`, `itemColorHover`, `itemColorActive`, `itemBackground`, `itemBackgroundHover`, `itemBackgroundActive`, `itemDecoration`, `itemDecorationHover`, `itemWeight`, `itemWeightActive`, `itemPadding`, `itemRadius`, `itemGap`, `submenuBackground`, `panelWidth`, `panelBackground`
`controls`	`controlBackground`, `controlColor`, `controlBorder`, `controlRadius`, `controlPadding`, `controlFocus`
`buttons`	`buttonBackground`, `buttonColor`, `buttonBorder`, `buttonRadius`, `buttonPadding`
`choices`	`controlBackgroundActive`, `controlColorActive`, `controlBorderActive`, `popoverBackground`
`results`	`resultsColumns`, `resultsGap`
`carousel`	`controlSize`, `dotColor`, `dotColorActive`, `controlsInset`
`link`	`linkColor`, `linkColorHover`, `linkDecoration`, `linkDecorationHover`
`fields`	`labelColor`, `labelSize`, `labelWeight`, `helpColor`, `legendColor`, `legendSize`, `legendWeight`, `legendLine`, `markColor`, `optionalColor`, `optionalSize`, `optionalWeight`, `numberSize`, `numberBorder`, `numberColor`, `numberFont`, `numberFontSize`, `numberWeight`, `controlMinHeight`, `controlBorderHover`, `placeholderColor`, `checkSize`, `checkAccent`, `navJustify`, `fieldGap`, `fieldMinHeight`

Permissions: —

Edition: Free

Known limits: an unknown key produces unknown style property. A known key of a group that the block does not have produces style_group_unsupported.

Third-party blocks

What it does: a plugin registers its own blocks.

How to use:

add_action('nucleo/register_blocks', function (Nucleo\Blocks\Registry $r) {
    $r->register(__DIR__ . '/blocks/hero');
});

Parameters: folder with block.nucleo.json.

Permissions: —

Edition: Free

Known limits: the action runs once, when Nucleo builds the block registry. A name already registered is an error.

06Structure blocks

`nc/section`

What it does: full-width band with an inner container div.nc-section__inner.

How to use: "type": "nc/section". Parents: any. Children: any.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.tag`	string	`section`, `header`, `footer`, `main`, `div`, `aside`, `nav`	`section`	External HTML element.
`settings.anchor`	string	—	—	Becomes `id` only if it matches `^[a-z][a-z0-9-]{0,63}$`.

Style: spacing, size, color, border, layout, position, motion, typography.

Permissions: those of the document save.

Edition: Free

Known limits: a non-compliant anchor produces no error: the renderer omits the id. The settings.tag sets the landmark semantics.

`nc/container`

What it does: flex or grid container for columns and groups of blocks. With href and label it becomes a clickable card.

How to use: "type": "nc/container". Parents: any. Children: any.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.layout`	string	`flex`, `grid`	`flex`	Class `nc-container--flex` or `--grid`.
`settings.responsiveMode`	string	`media`, `container`	—	`container`: the node gets `container-type:inline-size`.
`settings.anchor`	string	—	—	As in `nc/section`.
`settings.href`	string	URL or internal reference	—	With `label`, adds a link `a.nc-container__link` that covers the container.
`settings.label`	string	—	—	Accessible name (`aria-label`) of the link.

Style: spacing, size, color, border, effects, layout, position, motion, typography.

Permissions: those of the document save.

Edition: Free

Known limits: the link appears only with both href and label not empty. A javascript:, data: or vbscript: scheme removes the link.

`nc/spacer`

What it does: empty vertical space. Prints <div aria-hidden="true">.

How to use: "type": "nc/spacer" with style.height. Children: none.

Parameters: none.

Style: size, color, motion.

Permissions: those of the document save.

Edition: Free

Known limits: the manifest excludes color with styleExclude but declares it among the supported styles. The declared group wins: color stays allowed.

`nc/divider`

What it does: horizontal line <hr>.

How to use: "type": "nc/divider". Children: none.

Parameters: none.

Style: spacing, size, color, border, motion, typography.

Permissions: those of the document save.

Edition: Free

Known limits: none found.

`nc/section-ref`

What it does: inserts a reusable section (nucleo_section) by slug, with the parameter values.

How to use:

{ "id": "p1", "type": "nc/section-ref",
  "settings": { "section": "product-card", "params": { "title": "Magnesium" } } }

Children: none. Expansion, dependencies and recompilation are described on the Compiler and runtime page. nucleo/section-list lists the sections.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.section`	string	`^[a-z0-9][a-z0-9_-]{0,199}$`	—	Required. Slug, not id.
`settings.params`	object	parameter name → value of the declared type	—

Style: no group (all the base groups are excluded).

Permissions: those of the document save. Drafts and private sections are used only if the saving user has edit_theme_options, or if there is no logged-in user (WP-Cron, WP-CLI).

Edition: Free

Known limits:

The renderer prints an empty string: the node is replaced before compilation.
Maximum 4 levels of nested sections.
Expansion errors: section slug missing, section loop, too many nested sections, section has no root, undeclared parameter, required parameter without value or default, use a value of type …, legacy ref not supported inside a reusable section.

07Text blocks

`nc/heading`

What it does: heading from h1 to h6.

How to use: "type": "nc/heading". Children: none. The supported binding is content.text.

Parameters:

Name	Type	Allowed values	Default	Note
`content.text`	inline-rich-text	—	—	Required, translatable.
`settings.level`	integer	1–6	`2`

Style: typography, color, spacing, border, size, motion.

Permissions: those of the document save.

Edition: Free

Known limits: the text is cleaned to the allowed tags: strong, em, b, i, br, p, ul, ol, li, span[class], a[href,target,rel]. Other tags lose the markup and keep the text. script and style disappear with their content.

`nc/text`

What it does: paragraph with limited rich text, in a <div>.

How to use: "type": "nc/text". Children: none. The supported binding is content.html.

Parameters:

Name	Type	Allowed values	Default	Note
`content.html`	inline-rich-text	tags allowed for rich text	—	Translatable.

Style: typography, color, spacing, border, size, motion. Part: link (the link in the text).

Permissions: those of the document save.

Edition: Free

Known limits: same cleaning as nc/heading.

`nc/list`

What it does: bulleted list <ul>, with an optional icon in front of each item.

How to use: "type": "nc/list". Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`content.items`	array of strings	rich text	—	Required.
`settings.icon`	string	icon name	—	Same icon for every item.

Style: typography, color, spacing, motion, size, border. Parts: item (the li), icon (the icon inside the li).

Permissions: those of the document save.

Edition: Free

Known limits: the validator does not check settings.icon. An unknown name does not print the icon, without error. Non-string items are skipped.

08Media blocks

`nc/image`

What it does: image with srcset, sizes, LCP priority or deferred loading, and <picture> with modern formats.

How to use: "type": "nc/image". Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`content.src`	string	allowed URL	—	Required.
`content.alt`	string	—	—	Ignored with `decorative`.
`content.width`, `content.height`	integer	`> 0`	—	Written only if positive.
`content.srcset`, `content.sizes`	string	—	—	Without `srcset`, for an image of the media library the compiler uses the WordPress `srcset` with the intermediate sizes of the attachment, and writes the file's `width` and `height` if they are missing. Without `sizes`, inside an ancestor with a numeric `style.columns`, `sizes` follows the column width per breakpoint, for example `(min-width: 768px) min(33.33vw, 1280px), min(100vw, 1280px)`. Outside columns and with a known `width`: `(max-width: Wpx) 100vw, Wpx`.
`content.id`	string	digits	—	Attachment id. Otherwise the renderer looks it up from the URL.
`content.sources`	array	`{type, srcset}`; `type`: `image/avif`, `image/webp`, `image/png`, `image/jpeg`	—	Manual sources of `<picture>`: they win over the automatic ones.
`settings.decorative`	boolean	—	`false`	`alt=""` and no LCP priority.
`settings.formats`	string	`auto`, `off`	`auto`	`off`: no `<picture>`.

Style: size, border, effects, spacing, position, motion, typography, color.

Permissions: those of the document save.

Edition: Free

Known limits: the first non-decorative image of the document gets fetchpriority="high", the others loading="lazy". The automatic sources require the site option imageFormats.

`nc/icon`

What it does: inline SVG icon. A site icon wins over an internal icon with the same name.

How to use:

{ "id": "i1", "type": "nc/icon", "settings": { "name": "phone" } }

Children: none. Site icons are added with nucleo-icons-set or with the CLI (nucleo icons import, nucleo icons add, see the Local CLI page).

Parameters:

Name	Type	Allowed values	Default	Note
`content.label`	string	—	—	With label: `role="img"` and `aria-label`. Without: `aria-hidden="true"`.
`settings.name`	string	`^[a-z][a-z0-9-]{0,40}$`, internal or site icon	—

Style: size, color, spacing, motion, typography, border.

Permissions: those of the document save.

Edition: Free

Known limits:

Internal icons (25): check, arrow-right, phone, mail, map-pin, star, menu, close, plus, minus, clock, truck, wrench, shield, calendar, info, external-link, chevron-down, car, bus, tractor, search, gauge, layers, refresh.
An unknown name produces unknown icon with the list in allowed.
The internal icons use a 24×24 grid, currentColor stroke.

`nc/logo`

What it does: site logo (the WordPress custom logo) with explicit width and height, or the site name. Linked to the home page.

How to use: "type": "nc/logo". Children: none.

Parameters: none.

Style: size, spacing, motion, typography, color, border.

Permissions: those of the document save.

Edition: Free

Known limits: the logo is written on save. The site dependency recompiles the document when it changes.

`nc/video`

What it does: YouTube or Vimeo video with a static thumbnail. The iframe loads on click.

How to use: "type": "nc/video". Children: none. Script view.js, strategy interaction.

Parameters:

Name	Type	Allowed values	Default	Note
`content.provider`	string	`youtube`, `vimeo`	—	Required.
`content.videoId`	string	YouTube `^[A-Za-z0-9_-]{6,20}$`; Vimeo digits only	—	Required. A non-compliant id becomes empty.
`content.title`	string	—	—	Required, translatable. Button name: `Play: <title>`.
`content.poster`	string	`https://…` or a path starting with `/`	—	Without poster: `i.ytimg.com` thumbnail for YouTube, no image for Vimeo.
`settings.consent`	string	`marketing`, `statistics`, `preferences`, `none`	`marketing`	Category of the consent plugin.

Style: size, border, motion, spacing, typography, color.

Permissions: those of the document save.

Edition: Free

Known limits: with a consent plugin active and consent other than none, the block shows The video loads after cookie consent.. The provider thumbnail waits for consent. A custom poster loads at once.

`nc/slider`

What it does: carousel. Effect slide (scroll-snap) or fade (one slide at a time). Arrows, dots, autoplay with a pause button.

How to use: "type": "nc/slider". Each child is a slide. Children: any. Script view.js, strategy visible.

Parameters:

Name	Type	Allowed values	Default	Note
`content.label`	string	—	`Gallery`	Accessible name of the carousel.
`content.prevLabel`, `nextLabel`, `pauseLabel`, `playLabel`	string	—	translated texts	Button names.
`settings.perView`	integer	1–4	`1`	Ignored with `fade`.
`settings.arrows`	boolean	—	`true`
`settings.effect`	string	`slide`, `fade`	`slide`
`settings.autoplay`	integer	0–30	`0`	Seconds between slides. With a value `> 0` the pause button appears.
`settings.loop`	boolean	—	`true`
`settings.dots`	boolean	—	`false`
`settings.controlsPosition`	string	`below`, `bottom-left`, `bottom-right`, `bottom-center`	`below`	Outside `below` the controls sit over the slides.
`settings.speed`	integer	100–3000	`500`	Milliseconds, variable `--nc-slider-speed`.
`settings.pauseOnHover`	boolean	—	`true`

Style: spacing, border, motion, controls, carousel, size, typography, color.

Permissions: those of the document save.

Edition: Free

Known limits:

The manifest uses min and max, which the validator ignores. A value out of range passes validation and the renderer brings it back into range.
The default button names use the language of the user who saves. For a site in another language, write them in content.

`nc/embed`

What it does: YouTube or Vimeo video, Google Maps or another https address, with a static thumbnail. The iframe loads only on click.

How to use:

{ "id": "e1", "type": "nc/embed",
  "content": { "title": "Guided visit" },
  "settings": { "url": "https://youtu.be/abcDEF12345", "aspectRatio": "4:3" } }

Children: none. Script view.js, strategy interaction.

Parameters:

Name	Type	Allowed values	Default	Note
`content.title`	string	—	—	Required, translatable. Button name: `Load: <title>`.
`content.poster`	string	`https://…` or a path starting with `/`	—	Without poster: `i.ytimg.com` thumbnail for YouTube, no image for the others.
`settings.url`	string	`https://` to YouTube, Vimeo, Google Maps or another site	—	Required.
`settings.aspectRatio`	string	`16:9`, `4:3`, `1:1`, `21:9`	`16:9`	Proportion of the video area.
`settings.consent`	string	`marketing`, `statistics`, `preferences`, `none`	`marketing`	Category of the consent plugin, as in `nc/video`.

Style: size, spacing, typography, color, border, motion.

Permissions: those of the document save.

Edition: Free

Known limits:

The validator reports unsafe_url if settings.url is not https://, and invalid_url if the YouTube or Vimeo address has no valid id. With an invalid address the renderer prints nothing.
YouTube (youtube.com, m.youtube.com, youtube-nocookie.com, youtu.be) requires an id of 6–20 characters. Vimeo (vimeo.com, player.vimeo.com) requires a numeric id. Google Maps is recognized separately. Every other https becomes a generic iframe.
With a consent plugin active and consent other than none, the provider thumbnail waits for consent and The content loads after cookie consent. appears.

09Action and interactive blocks

`nc/button`

What it does: link with the look of a button. Without href it is a <button type="button">.

How to use: "type": "nc/button". Children: none. The supported binding is content.text.

Parameters:

Name	Type	Allowed values	Default	Note
`content.text`	string	—	—	Required, translatable.
`settings.href`	string	URL or internal reference	—
`settings.variant`	string	`primary`, `secondary`, `link`	`primary`	Class `nc-button--<variant>`.
`settings.newTab`	boolean	—	`false`	`target="_blank" rel="noopener"`.

Style: typography, color, spacing, size, border, motion.

Permissions: those of the document save.

Edition: Free

Known limits: an href with a javascript:, data: or vbscript: scheme turns the link into a <button>.

`nc/accordion`

What it does: expandable sections with details and summary. Optional: JSON-LD FAQPage.

How to use: "type": "nc/accordion". Children: none. No script.

Parameters:

Name	Type	Allowed values	Default	Note
`content.items`	array	`{title: string, html: rich-text}`, both required	—	Required, translatable.
`settings.openFirst`	boolean	—	`false`	First item open.
`settings.faq`	boolean	—	`false`	Adds `<script type="application/ld+json">` `FAQPage`.
`settings.icon`	string	`chevron`, `plus`	`chevron`	`plus`: class `nc-accordion--plus`.

Style: spacing, color, typography, border, motion, size. Parts: item, summary, panel.

Permissions: those of the document save.

Edition: Free

Known limits: the nucleo/faq_schema filter with false removes the JSON-LD. Items with an empty question or answer do not enter the JSON-LD.

`nc/tabs`

What it does: ARIA tabs (tablist, tab, tabpanel). Without JavaScript all the panels stay visible.

How to use: "type": "nc/tabs". Children: none. Script view.js, strategy idle.

Parameters:

Name	Type	Allowed values	Default	Note
`content.items`	array	`{title: string, html: rich-text}`, both required	—	Required, translatable.

Style: spacing, color, typography, border, motion, size. Parts: tab, panel.

Permissions: those of the document save.

Edition: Free

Known limits: generated ids <id>-tab-N and <id>-panel-N. Without valid items the block prints nothing.

10Navigation blocks

`nc/menu`

What it does: WordPress menu with nested or dropdown submenus, an offcanvas panel and mega panels.

How to use: "type": "nc/menu", "settings": { "menu": 12 }. Children: only nc/mega-panel. Script view.js, strategy idle. Dependency menu:{settings.menu}.

Parameters:

Name	Type	Allowed values	Default	Note
`content.toggleLabel`	string	—	translated `Menu`	Text or `aria-label` of the offcanvas button.
`settings.menu`	integer	id of a menu	`0`
`settings.orientation`	string	`horizontal`, `vertical`	`horizontal`
`settings.mobile`	string	`none`, `offcanvas`	`none`
`settings.submenus`	string	`nested`, `dropdown`	`nested`	`dropdown` adds a button for each submenu.
`settings.toggle`	string	`text`, `icon`	`text`	`icon`: `menu` and `close` icons.
`settings.breakpoint`	string	`md`, `lg`, `xl`	`md`	Offcanvas threshold.
`settings.panelSide`	string	`left`, `right`	`left`

Style: typography, color, spacing, layout, border, motion, menu, size. Parts: list, link, submenu.

Permissions: those of the document save.

Edition: Free

Known limits:

With menu <= 0, a menu that does not exist or a menu without items, the block prints nothing, without error.
The aria-label of the <nav> is the menu name.
Every link carries data-nc-mi (item id), data-nc-mt (linked object) and data-nc-ma (ancestors). The runtime computes the current item (see the Compiler and runtime page).

`nc/mega-panel`

What it does: full-width panel linked to an nc/menu item. The manifest describes it as visible on mouse hover or focus from 768px.

How to use: child of nc/menu, with settings.item equal to the id of the item. Children: any, including an nc/section-ref.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.item`	integer	id of the menu item	`0`

Style: spacing, color, typography, border, position, motion, size.

Permissions: those of the document save.

Edition: Free

Known limits: the only allowed parent is nc/menu. With several panels on the same item, the first one applies. A panel with an item that matches no item does not appear.

`nc/breadcrumbs`

What it does: navigation path with JSON-LD BreadcrumbList. With Yoast or Rank Math active it uses the plugin output. It is dynamic: it is computed on every request.

How to use: "type": "nc/breadcrumbs". Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.homeLabel`	string	—	`Home`
`settings.archive`	boolean	—	`false`	Adds the archive of the content type.
`settings.parent`	object	`{label, href}`	—	Item in place of the archive. Empty or unresolved href: item without link.
`settings.taxonomy`	string	taxonomy slug	`""`	First term of the post with the parent terms.

Style: typography, color, spacing, motion, size, border. Parts: list, item, link, current.

Permissions: those of the document save.

Edition: Free

Known limits: with an SEO plugin the block settings do not apply. aria-label="Breadcrumb" is not translated. settings.parent.href does not go through the URL check of the validator.

`nc/search`

What it does: site search form (GET on home_url('/'), field s). Shows the current query.

How to use: "type": "nc/search". Children: none. Dynamic.

Parameters:

Name	Type	Allowed values	Default	Note
`content.label`	string	—	`Search`	Label of the field.
`content.buttonLabel`	string	—	`Search`	Button text.
`content.placeholder`	string	—	—
`settings.hideLabel`	boolean	—	`false`	Class `screen-reader-text` on the label.

Style: typography, color, spacing, size, controls, buttons, motion, border. Parts: label, input, button.

Permissions: those of the document save.

Edition: Free

Known limits: the normalizer does not add the defaults of content. Without text the runtime uses Search translated into the language of the visitor.

`nc/pagination`

What it does: links to the pages of the main query (paginate_links()). Dynamic.

How to use: "type": "nc/pagination" at the end of an archive. Children: none.

Parameters: none.

Style: typography, color, spacing, motion, size, border. Parts: link, current.

Permissions: those of the document save.

Edition: Free

Known limits: with only one page it prints nothing. aria-label="Paginazione" is written in Italian in the code and is not translated.

`nc/toc`

What it does: table of contents of the page in a <nav>. The script highlights the current section while scrolling.

How to use: children nc/text or nc/button with a #anchor link to an nc/section or nc/container of the page. Children: any. Script view.js, strategy visible.

Parameters:

Name	Type	Allowed values	Default	Note
`content.label`	string	—	—	`aria-label` of the `<nav>`. Translatable.

Style: spacing, size, color, border, effects, layout, position, motion, typography. Part: link. The current item is styled with the …Current keys.

Permissions: those of the document save.

Edition: Free

Known limits: the validator does not check the type of the children nor the anchors.

`nc/offcanvas`

What it does: trigger button that opens a side panel holding the child blocks. The panel is a modal dialog, hidden until the button is pressed. Without JavaScript it stays hidden.

How to use: "type": "nc/offcanvas", "settings": { "label": "Menu", "side": "right" }. Children: any, inside the panel. Script view.js, strategy idle.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.label`	string	—	—	Required, translatable. Text of the button and name of the panel. Empty: no output.
`settings.side`	string	`left`, `right`	`left`	Side of the panel.
`settings.width`	string	simple CSS length: `20rem`, `320px`, `80vw`, `50%`	`20rem`	Other value: `20rem` is used.

Style: size, spacing, typography, color, border, motion.

Permissions: those of the document save.

Edition: Free

Known limits: it is a panel for the children, not the menu. The menu has its own panel with settings.mobile of nc/menu.

11Post and archive blocks

These blocks are dynamic: the compiler writes a slot, and the runtime fills it on every request. Inside a card they read the post of the item, otherwise the request object.

`nc/post-title`

What it does: title of the current post.

How to use: "type": "nc/post-title". Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.tag`	string	`h1`, `h2`, `p`	`h1`
`settings.link`	boolean	—	`false`	The title becomes a link to the post.

Style: typography, color, spacing, link, motion, size, border. Part: link.

Permissions: those of the document save.

Edition: Free

Known limits: outside a post it prints nothing.

`nc/post-content`

What it does: content of the requested post, passed through the the_content filter.

How to use: once in the single layouts. Children: none.

Parameters: none.

Style: typography, color, spacing, motion, size, border. Part: link.

Permissions: those of the document save.

Edition: Free

Known limits: it always reads the request object, not the card. A guard prevents recursion. Not allowed in cards.

`nc/post-image`

What it does: featured image of the post, with <picture> and modern formats.

How to use: "type": "nc/post-image". Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.size`	string	registered size, `^[a-z0-9_-]+$`	`large`	Non-compliant value: `large`.
`settings.priority`	boolean	—	`false`	`fetchpriority="high"` and `loading="eager"`. Otherwise `lazy`.
`settings.formats`	string	`auto`, `off`	`auto`

Style: spacing, size, border, effects, motion, typography, color.

Permissions: those of the document save.

Edition: Free

Known limits: without a featured image it prints nothing.

`nc/post-meta`

What it does: date, author, categories and taxonomy terms of the post.

How to use:

{ "id": "m1", "type": "nc/post-meta", "settings": { "fields": ["date", "tax:genre"] } }

Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.fields`	array of strings	`^(date\	author\	categories\	tax:[a-z0-9_-]+)$`	`["date"]`	The date goes in `<time datetime>`.
`settings.terms`	string	`text`, `chips`	`text`	`chips`: class `nc-post-meta--chips`, terms without commas.

Style: typography, color, spacing, motion, size, border. Parts: item, term, link.

Permissions: those of the document save.

Edition: Free

Known limits: tax: shows only the visible taxonomies. Without items it prints nothing.

`nc/archive-title`

What it does: title of the archive without the prefix ("Category:"). With a search: Results for: <query>.

How to use: "type": "nc/archive-title". Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.level`	integer	1, 2, 3	`1`

Style: typography, color, spacing, motion, size, border.

Permissions: those of the document save.

Edition: Free

Known limits: empty title: no output.

`nc/archive-description`

What it does: description of the archive, filtered with wp_kses_post.

How to use: "type": "nc/archive-description". Children: none.

Parameters: none.

Style: typography, color, spacing, motion, size, border.

Permissions: those of the document save.

Edition: Free

Known limits: empty description: no output.

12List and collection blocks

The cards of nc/query, nc/collection and the rows of nc/repeater follow these rules:

Blocks not allowed: nc/query, nc/collection, nc/pagination, nc/form, nc/native-form, nc/search, nc/breadcrumbs, nc/archive-title, nc/archive-description, nc/post-content, nc/menu, nc/mega-panel and every woo/*.
Bind sources not allowed: user, query.
Allowed visibility.when conditions: only filled and empty.

The error is always card_block_not_allowed. Binding and runtime of the cards are described on the Dynamic data page.

`nc/query`

What it does: list of posts built on save. With relatedTo it becomes a slot: posts related to the current post, computed on every request and cached.

How to use: without children it uses a fixed card: medium_large image, h2 title with link, excerpt. With one child, the child is the card repeated for each post. Children: at most 1. Dependency query:{settings.postType}.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.postType`	string	registered content type	`post`	Non-existent type: empty list.
`settings.perPage`	integer	1–24	`6`
`settings.taxonomy`	string	taxonomy slug	`""`	Fixed filter, with `term`.
`settings.term`	string	term slug	`""`
`settings.relatedTo`	string	taxonomy slug	`""`	Posts of the same type with a term in common, excluding the current one.
`settings.orderby`	string	`date`, `title`	`date`	`date` descending, `title` ascending.
`settings.empty`	string	—	`No content`	Text without results. With `relatedTo`, `""` prints nothing.

Style: spacing, layout, typography, color, position, motion, size, border.

Permissions: those of the document save.

Edition: Free

Known limits:

Only published posts without password.
Cache of relatedTo: group nucleo_related of the object cache, with persistence of 24 hours. Without a persistent object cache, the value goes into the _nucleo_related meta of the current post.
The default No content is in English and the renderer translation does not apply.

`nc/repeater`

What it does: repeats the child (the row) for each row of a repeater field of the current post. Dynamic.

How to use: one child with bind {"source": "item", "field": "<subfield>"}. The source item also offers index, from 1. Children: exactly 1.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.field`	string	key of a `repeater` field of the model	`""`	Empty: `field_missing` error.
`settings.tag`	string	`div`, `ul`, `ol`	`div`	With `ul` and `ol` each row is in `li.nc-repeater__item`.
`settings.empty`	string	—	`""`	Text without rows. Empty: no output.

Style: spacing, layout, typography, color, motion, size, border.

Permissions: those of the document save.

Edition: Free for the block. The repeater field of the content model is Pro.

Pro

The block reads only the repeater fields of the Nucleo content model.

Known limits: a nc/repeater inside a row is not allowed (card_block_not_allowed). index does not replace a subfield with the same name.

`nc/collection`

What it does: filterable and sortable list of posts, terms or data from a component. Filters and results update without reloading the page.

How to use: allowed children nc/collection-card (exactly one), nc/collection-count, nc/collection-reset, nc/collection-empty. Script view.js, strategy visible. Dependency query:{settings.postType}. Runtime, filter URLs and component sources are described on the Dynamic data page.

Parameters:

Name	Type	Allowed values	Default	Note
`content.filtersLabel`, `applyLabel`, `moreLabel`, `sortLabel`, `closeLabel`, `resultsLabel`, `allLabel`, `upcomingLabel`, `pastLabel`, `monthLabel`, `fromLabel`, `toLabel`, `gridLabel`, `rowsLabel`	string	—	plugin translations	`resultsLabel`: `{count}` or `%d`; `singular\	plural`.
`settings.source`	string	`posts`, `component`, `terms`	`posts`
`settings.component`	string	registered data source	`""`	With `source: component`.
`settings.postType`	string	public type of the model	`""`	With `source: posts`.
`settings.taxonomy`	string	public taxonomy, not `nav_menu` nor `wp_*`	`""`	With `source: terms`.
`settings.parent`	string	`""` (all), `"0"` (top level), term slug	`""`	With `source: terms`.
`settings.hideEmpty`	boolean	—	`true`	With `source: terms`.
`settings.cardSize`	string	`auto`, `small`	`auto`	`small`: minimum column 9rem instead of 16rem.
`settings.perPage`	integer	1–48	`12`
`settings.orderby`	string	posts: `date`, `title`, `menu_order`, `field:<key>`; terms: `name`, `slug`, `count`, `field:<key>`	posts `date`, terms `name`	`field:` requires a `number`, `date`, `text` or `select` field.
`settings.order`	string	`asc`, `desc`	posts `desc`, terms `asc`
`settings.prefix`	string	—	`f`	Prefix of the URL parameters.
`settings.filters`	array	max 12 items	`[]`	See below.
`settings.sorts`	array	max 8; `{key, label, orderby, order}` all required	`[]`
`settings.views`	array	`grid`, `rows`	`["grid"]`
`settings.paging`	string	`pages`, `more`, `none`	`pages`
`settings.counts`	boolean	—	`true`
`settings.mobileFilters`	string	`drawer`, `inline`	`drawer`

Item of settings.filters (key, label, type, ui required):

`type`	Keys	Allowed `ui`
`taxonomy`	`taxonomy` linked to the content type, `multiple?`	`pills`, `select`, `checkboxes`, `dropdown`
`field`	`field` of type `select` or `boolean`	`pills`, `select`, `checkboxes`, `dropdown`
`field`	`field` of type `number` or `date`	`range`
`date`	`field?` of type `date`, `presets?` (`upcoming`, `past`, `month`)	`pills`, `select`, `range`
`search`	—	`text`
`param`	`param` declared by the `component` source. With `range` you need `<param>_min` and `<param>_max`	—

Style: spacing, layout, typography, color, position, motion, controls, buttons, choices, border, results, size. resultsColumns: from 1 to 12 columns, also per breakpoint.

Permissions: those of the document save.

Edition: Free

Known limits:

Validation codes: unknown_component, unknown_post_type, unknown_taxonomy, unknown_term, unknown_field, terms_no_filters, duplicate_key, bad_ui, card_missing, card_term_source, card_block_not_allowed.
Reserved filter and sort keys: sort, page.
With source: terms the card cannot contain nc/post-title, nc/post-image, nc/post-meta, nc/repeater, nor sources post, nucleo, item, author, acf, metabox, jetengine.

`nc/collection-card`

What it does: card of nc/collection. Its only child repeats for each item.

How to use: child of nc/collection, with one child only (for example nc/container). Children: any, within the card rules.

Parameters: none.

Style: base groups. The renderer prints nothing: the style of the node has no visible effect.

Permissions: those of the document save.

Edition: Free

Known limits: the only allowed parent is nc/collection. More than one child: card_missing.

`nc/collection-count`

What it does: number of results of nc/collection.

How to use: optional child of nc/collection. Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`content.text`	string	`{count}` or `%d`; two forms `singular\	plural`	—	Without a placeholder the number goes first. A pipe preceded by a backslash is literal; `%%` writes `%`. Without text the `resultsLabel` of the collection applies.
`content.one`	string	—	—	Text for a single result.

Style: typography, color, spacing, size, border, motion. The collection applies the classes of the node.

Permissions: those of the document save.

Edition: Free

Known limits: the only allowed parent is nc/collection.

`nc/collection-empty`

What it does: content shown by nc/collection when there are no results.

How to use: optional child of nc/collection, for example with an nc/text. Children: any.

Parameters: none.

Style: base groups. The collection prints only the children: the style of the node has no visible effect.

Permissions: those of the document save.

Edition: Free

Known limits: without this block the collection shows nothing when there are no results.

`nc/collection-reset`

What it does: link that clears the filters of nc/collection.

How to use: optional child of nc/collection. Children: none.

Parameters:

Name	Type	Allowed values	Default	Note
`content.text`	string	—	—	Text of the link. Translatable.

Style: typography, color, spacing, border, size, motion. The collection applies the classes of the node.

Permissions: those of the document save.

Edition: Free

Known limits: the only allowed parent is nc/collection.

13Code blocks

These two blocks print code that does not pass the style and accessibility checks. They require unfiltered_html.

`nc/html`

What it does: prints the HTML code as written, inside a div with the classes of the block. WordPress does not filter it.

How to use: "type": "nc/html", "content": { "html": "<p>Text</p>" }. Children: none. Use it only when no other block fits: for rich text prefer nc/text.

Parameters:

Name	Type	Allowed values	Default	Note
`content.html`	string	—	—	Required. Printed without cleaning.

Style: size, spacing, typography, color, border, motion.

Permissions: whoever saves the document must have unfiltered_html, otherwise the content is not kept.

Edition: Free

Known limits: the code is not checked for style or accessibility.

`nc/shortcode`

What it does: prints the output of a WordPress shortcode, run on every request.

How to use: "type": "nc/shortcode", "content": { "shortcode": "[gallery ids=\"1,2\"]" }. Children: none. Prefer a native block when one exists.

Parameters:

Name	Type	Allowed values	Default	Note
`content.shortcode`	string	starts with `[` and ends with `]`	—	Required.

Style: size, spacing, typography, color, border, motion.

Permissions: whoever saves the document must have unfiltered_html, otherwise the content is not kept.

Edition: Free

Known limits: the validator checks only the […] form. The shortcode is not verified.

14Form blocks

`nc/form`

What it does: inserts a form from an external plugin with its shortcode, on every request.

How to use:

{ "id": "f1", "type": "nc/form", "settings": { "plugin": "cf7", "id": "123" } }

Children: none. Dependency form:{settings.plugin}.

Parameters:

Name	Type	Allowed values	Default	Note
`settings.plugin`	string	`cf7`, `gravity`, `wpforms`, `fluent`	—	Required. Shortcode: `contact-form-7`, `gravityform … ajax="true"`, `wpforms`, `fluentform`.
`settings.id`	string	—	—	Required. Id of the form in the plugin.

Style: spacing, typography, motion, size, color, border.

Permissions: those of the document save.

Edition: Free

Warning

The block does not check that the plugin is active. With an empty id it prints nothing.

`nc/native-form`

What it does: native form with fields, steps and actions: code verification by email, save, email, webhook, post creation, component action.

How to use: "type": "nc/native-form". Children: none. Script view.js, strategy interaction. Submission, captcha, OTP and runtime actions are described on the Dynamic data page.

Parameters:

Name	Type	Allowed values	Default	Note
`content.submitLabel`, `successMessage`, `errorMessage`, `codeLabel`, `nextLabel`, `backLabel`, `sentMessage`, `sendCodeLabel`, `verifyLabel`, `otpFailedMessage`, `expiredMessage`, `requiredMark`, `optionalMark`, `captchaMessage`	string	—	—	Translatable.
`settings.fields`	array	max 40	`[]`	See below.
`settings.steps`	array	`{title}` required	`[]`
`settings.actions`	array	see below	`[]`
`settings.redirect`	string	`home`, `page:<slug>`, URL	—	Empty: the result message stays.
`settings.captcha`	boolean	—	`true`	`false` removes the site captcha from this form.
`settings.groupNumbering`	string	`none`, `letters`, `numbers`, `letters-box`, `numbers-box`	`none`	Numbers the legends of the groups.

Item of settings.fields (name and type required):

Key	Type	Allowed values	Default
`name`	string	unique in the form	—
`type`	string	`text`, `email`, `tel`, `url`, `textarea`, `number`, `date`, `select`, `radio`, `checkboxes`, `checkbox`, `consent`, `hidden`, `context`	—
`label`, `help`, `placeholder`, `group`	string	—	—
`required`	boolean	—	—
`step`	integer	`>= 0`, below the number of steps	`0`
`maxLength`	integer	`>= 1`	—
`min`, `max`	number or string	—	—
`decimals`	integer	`>= 0`	—
`options`	array	`{value, label?}`; required for `select`, `radio`, `checkboxes`	—
`value`	string or number	—	—
`from`	string	`post.id`, `post.title`, `post.url`	—
`width`	string	`full`, `half`	`full`

Item of settings.actions (type required):

`type`	Keys	Rules
`otp`	`field`, `subject?`, `body?`, `ttl` (5–30, default 15), `step?`	First action. `field` of type `email`. `step` below the last step and not before the step of the field.
`save`	—	—
`email`	`to`, `replyTo?`, `subject?`, `body?`	`to: "field:<name>"` requires an `otp` on the same field.
`webhook`	`url`	Only `https://`.
`create-post`	`postType`, `status`, `title?`, `fields?`	`postType` of the model. `status` `draft` or `pending`.
`component`	`name`, `input?`	Action registered by a plugin.

Style: size, spacing, typography, color, border, motion, controls, buttons, fields. Parts: field, label, legend, number, legendLine, mark, optional, help, control, placeholder, check, nav, button, message.

Permissions: those of the document save.

Edition: Free

Known limits:

Validation codes: duplicate_field, bad_options, bad_step, otp_first, otp_step, unverified_recipient, unknown_field, unknown_post_type, bad_status, unsafe_url, unknown_component.
The placeholders {field:<name>} in subject, body, title, fields and input must cite a field of the form (unknown_field).

Was this page helpful?