Skip to Content

Widgets

Widgets are the content blocks inside layout placeholders. Each is a React component that receives its settings from Visor.

How a widget is found

components/Widget.tsx works out the component from the widget’s collection name:

  1. It takes item.widget_definition.name, or the collection otherwise.
  2. It strips any xtr_cms_widget_ prefix and converts snake_case to PascalCase.
  3. In draft mode, it adds Client to the front.
CollectionComponentIn Visor’s editor
site_heroSiteHeroClientSiteHero
vds_rich_textVdsRichTextClientVdsRichText

If there’s no match, it renders a “Widget not found” message. A widget receives data (with its parameters), content, searchParams, limit, draftMode and slugSegments.

Widgets included

Design-system widgets are what people see in Visor’s Widgets panel.

CategoryWidgets
Hero & bannersHero, Call to action band
PagePage header
ContentRich text, Callout, Feature grid, Steps
MediaMedia and text, Video
Social proofStatistics, Testimonials, Logo cloud
PricingPricing
Data & listingsPage listing, Article list
SearchSite search, Article search
InteractiveFAQ
NavigationSite header, Site footer, Breadcrumb, On this page, Section navigation

Older platform widgets, such as HeroBanner, Cards and ContentBlock, are hidden from the panel but keep working on pages that use them. docs/DESIGN_SYSTEM.md in the repository maps each one to its replacement.

components/widgets/site-widgets/ also ships with samples to learn from: BaseWidget, SampleConfigurationForm and ChocolateFactoryChat.

Create a site widget

The create-widget skill does all of this for you. Here’s what it creates:

    • SiteHero.tsx
      • ClientSiteHero.tsx
      • SiteHeroSlider.tsx

Write the server widget

This is what the published website renders. It exports widgetJsonConfiguration, and the collection must match the file name.

// components/widgets/site-widgets/SiteHero.tsx export const widgetJsonConfiguration = { type: "widget", name: "Site hero", icon: "image", collection: "site_hero", id: "site_hero", category: "Hero & banners", categoryIcon: "panorama", item: { id: "site_hero", name: "Site hero", placeholder_definition: { name: "Main" }, widget_definition: { name: "site_hero" }, parameters: { title: "", description: "" }, }, }; export default function SiteHero({ data }) { const { title, description } = data?.parameters ?? {}; return ( <section className="site-hero"> <h2>{title}</h2> <p>{description}</p> </section> ); }

Write the client variant

This is what Visor’s editor renders, and it’s required, even for a static widget. Wrap the markup in FormConfigurationProvider and pass your formFields.

// components/widgets/site-widgets/client/ClientSiteHero.tsx "use client"; import { useState } from "react"; import FormConfigurationProvider from "@/components/form-configuration/FormConfigurationProvider"; const formFields = [ { name: "title", label: "Title", type: "InputText" }, { name: "description", label: "Description", type: "InputTextarea" }, ]; export default function ClientSiteHero({ data, draftMode, searchParams }) { const [formValue, setFormValue] = useState({ title: data.parameters?.title ?? "", description: data.parameters?.description ?? "", }); return ( <FormConfigurationProvider data={data} draftMode={draftMode} searchParams={searchParams} setFormValue={setFormValue} formFields={formFields} formValue={formValue} > <section className="site-hero"> <h2>{formValue.title}</h2> <p>{formValue.description}</p> </section> </FormConfigurationProvider> ); }

Give each field its default with ??, one field at a time. Don’t spread data.parameters and then set defaults, because a saved empty value would be overwritten.

Add its styles

Put them in styles/site/widgets/<name>.scss, using design tokens and BEM names, and add a @use line in styles/site/index.scss. See Themes.

Check it

It should appear in http://localhost:3000/api/widgets, and in the Widgets panel in Developer mode. After you merge it, everyone sees it.

Rules

  • Interactive parts: put "use client" parts in site-widgets/<Name>/<Name><Part>.tsx and import them in both the server and client variants. The published website renders only the server widget, so behaviour that exists only in the client variant won’t work there.
  • Helpers: keep them in shared/*.ts. Every .tsx file under the widget folders is registered as a widget.
  • On/off options are strings, never booleans.
  • Links in the client variant render as <span>, so clicks don’t navigate away from the editor.
  • Tests: use .test.ts, not .test.tsx, under components/widgets, because .tsx files get bundled.

Form fields

The type of a field is a file name in fields/platform-fields/ or your own fields/site-fields/.

KindTypes
BasicInputText, InputTextarea, InputSelect, InputRadio, InputCheckbox, InputWysiwyg, InputFile
From Visor’s dataInputDataSourceDropdown, InputDataSourceCheckbox, InputDataSourceSearchEngine, and others beginning InputDataSource
RowsRepeatable

Categories

Choose by what the widget does, never by brand. npm test fails on any other value.

categorycategoryIcon
Hero & bannerspanorama
Contentinsert_text
Mediaperm_media
Social proofreviews
Pricingsell
Data & listingsdataset_linked
Formsdynamic_form
Navigationmenu
Pagearticle
Searchmanage_search
Interactivetouch_app

Naming

A site widget’s name must not match any .tsx file under platform-widgets/, including subfolders, because the platform’s wins with a warning. npm run check:site-layer catches clashes. Prefix names with Site or your site’s name. Vds* belongs to the platform.

Widgets that read content types

See Content Types in Code.

Last updated on