Defining a Widget

One call

import type { WidgetComponentProps, WidgetData } from '@vitnode/core/widgets'

import { defineWidget } from '@vitnode/core/widgets'
import { field } from '@vitnode/core/content'

const calloutFields = {
  body: field.textarea({ required: true, minLength: 1, maxLength: 600 }),
  title: field.text({ required: true, minLength: 1, maxLength: 120 }),
  tone: field.enum({
    defaultValue: 'info',
    values: ['info', 'success', 'warning'],
  }),
}

type CalloutData = WidgetData<typeof calloutFields>

const Callout = ({ data }: WidgetComponentProps<CalloutData>) => (
  <aside>
    <h2>{data.title}</h2>
    <p>{data.body}</p>
  </aside>
)

export const calloutWidget = defineWidget({
  component: Callout,
  description: 'A short highlighted note in one of three tones.',
  fields: calloutFields,
  id: 'callout',
  name: 'Callout',
})

WidgetData<typeof calloutFields> is the inferred data type: title and body are string, tone is "info" | "success" | "warning" | undefined because it has a default. Nothing is written twice.

Component props

interface WidgetComponentProps<TData> {
  /** The instance's own stable id - not the widget's. */
  widgetId: string
  data: TData
  index: number
  type: string
  variant?: string
}

data has already been through the widget's schema when the component runs, so a component never checks for missing fields. variant is the look this instance picked, and is undefined for a widget that offers none.

Two looks, one widget

A widget that should render the same content in more than one shape declares its shapes instead of growing a style field:

export const featuresWidget = defineWidget({
  component: Features,
  defaultVariant: 'grid',
  fields: featuresFields,
  id: 'features',
  variants: [{ id: 'grid' }, { id: 'list' }, { id: 'compact' }],
})

The chosen variant is stored beside the instance's data, never inside it, and the editor grows a picker for it with no further work. See Block Variants for the resolution rules and what happens to a stored variant a block stops offering.

Ids are namespaced for you

Write id: "callout". The registry prefixes the namespace of the plugin that registered it, derived from the last segment of the package name:

Writing the namespace yourself is an error - a block would otherwise be addressable under two names, and content written under the wrong one would be unrenderable.

Two packages whose names end in the same segment (@vitnode/blog and @acme/blog) collide. The registry refuses to build and names both; set namespace on one of their blocks modules to settle it.

Which fields a block may hold

Every one of those rules lives in one table, blockFieldKindRefusal, and the error a refused field produces quotes the reason from it.

Localization

A widget's fields are never localized: true. There is no translation row for them to live in, and per-field locale maps inside JSON would be a second localization system that revisions, preview and the public locale resolution know nothing about.

The zone is what translates:

content: field.widgets({ localized: true })

This is document-level localization, not translated field values: each language gets its own widgets, in its own order, and the two need not correspond at all.

en:  Hero  →  Text  →  CTA
pl:  Hero  →  CTA   →  Gallery

See The blocks() field.

Editing a widget's text in the properties panel changes nothing about this. What somebody types goes into the data of the snapshot the page mounted for the locale it is showing, and it is saved by whoever already owned that locale's zone.

Validating data by hand

A definition is metadata: an id, the field map and the component. It carries no schema of its own, which is what keeps defineWidget - and therefore every public page that renders a widget - free of a validation library. The schema is derived from the fields on demand:

import { parseWidgetData, widgetDataSchema } from '@vitnode/core/widgets'

const data = parseWidgetData(calloutWidget, { title: 'Heads up', body: '...' })
// { title: "Heads up", body: "...", tone: "info" }

widgetDataSchema(calloutWidget).safeParse(input)

parseWidgetData applies defaults and throws a BlockError naming the field when the value does not fit; its return type is inferred from the definition's field map. widgetDataSchema is the underlying Zod object, built once per definition and cached.

A variant is not part of that schema, and neither is the arrangement of the widgets around this one - those are the instance's variant and its Area's layout. The rule of thumb: data is what the widget says, variant is how this instance says it, Area.layout is how widgets sit together.

The Content Engine calls these for you on every write. You need them only when you are producing widget data outside the API - a seed, a migration, an importer.