Widgets
Widgets
Widgets are configurable page sections that VitNode plugins define and moderators place. See how they are defined, stored, rendered and edited.
A widget is a page section somebody can place, in an order they choose: a hero, a paragraph of prose, a call to action, a list of features. A plugin defines it once, with the fields it holds and one React component that renders them, and any content type or editable page in the installation can offer it.
"Widget" is the name people see in the UI. In code the same thing is a
block: defineBlock, field.blocks(), blocksRegistry. Most APIs export
both names (defineWidget is defineBlock), so use whichever reads better.
How the pieces fit
defineWidget() a widget: fields + one component, in a plugin
ā
src/widgets.tsx exported as `blocks`, and passed to buildApiPlugin({ blocks })
ā
stored in a blocks() field on a content record
or an editable page's layout (core stores it)
ā
<ContentZone> a named place on a page that renders them
ā
visual editor Edit widgets in the user menu, for moderatorsRegistration is two lines in the plugin: the blocks export, which VitNode's Vite plugin collects into the app's generated src/blocks.gen.ts, and buildApiPlugin({ blocks }), which lets the API validate every write. First widget shows both.
What a widget is made of
| Part | What it is |
|---|---|
| Id | hero, written without a namespace. The registry adds the plugin's own, so it is stored as core:hero. |
| Fields | Content Engine field builders, the same field.text(), field.enum() and friends a content type uses. |
| Component | One React component. It receives the data stored for that instance and renders during SSR like any other component. |
A widget is not a content type. It has no table, no permissions and no API routes of its own. It is a value inside a record or a page layout, so re-ordering a page is one UPDATE, not a migration. The API validates data once, when it is written; the renderer only checks that it still fits the widget's fields (see Validation).
Widgets that ship with core
| Id | What it renders |
|---|---|
core:hero | A page heading with an optional eyebrow, lead paragraph and one link. |
core:text | Plain paragraphs of prose. Blank lines separate paragraphs; nothing is parsed as markup. |
core:cta | A short call to action with one link. |
Find your guide
| I want to | Guide |
|---|---|
| Build a widget from definition to a public page | First widget |
| Define a widget's fields, icon and component | Define a widget |
| Store widgets on a content type | Blocks field |
| Render a stored list of widgets | Render widgets |
| Give widgets a named place on a page | Content zones |
| Put several zones on one page, around application UI | Several zones |
| Limit which widgets a place accepts | Restrict widgets |
| Let moderators arrange a page in the browser | Editable pages |
| Load and save an editable page yourself | Custom loader |
| Understand how layouts are saved, checked and conflict-proofed | Saving layouts |
| Give one widget several looks | Variants |
| Put widgets side by side in columns | Layout areas |
| Arrange widgets as a moderator | Visual editor |
| Edit widgets stored in your own table | Custom editor host |