Skip to Content
Documentation

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 or block?

"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 moderators

Registration 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

PartWhat it is
Idhero, written without a namespace. The registry adds the plugin's own, so it is stored as core:hero.
FieldsContent Engine field builders, the same field.text(), field.enum() and friends a content type uses.
ComponentOne 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

IdWhat it renders
core:heroA page heading with an optional eyebrow, lead paragraph and one link.
core:textPlain paragraphs of prose. Blank lines separate paragraphs; nothing is parsed as markup.
core:ctaA short call to action with one link.

Find your guide

I want toGuide
Build a widget from definition to a public pageFirst widget
Define a widget's fields, icon and componentDefine a widget
Store widgets on a content typeBlocks field
Render a stored list of widgetsRender widgets
Give widgets a named place on a pageContent zones
Put several zones on one page, around application UISeveral zones
Limit which widgets a place acceptsRestrict widgets
Let moderators arrange a page in the browserEditable pages
Load and save an editable page yourselfCustom loader
Understand how layouts are saved, checked and conflict-proofedSaving layouts
Give one widget several looksVariants
Put widgets side by side in columnsLayout areas
Arrange widgets as a moderatorVisual editor
Edit widgets stored in your own tableCustom editor host