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:
- It takes
item.widget_definition.name, or thecollectionotherwise. - It strips any
xtr_cms_widget_prefix and convertssnake_casetoPascalCase. - In draft mode, it adds
Clientto the front.
| Collection | Component | In Visor’s editor |
|---|---|---|
site_hero | SiteHero | ClientSiteHero |
vds_rich_text | VdsRichText | ClientVdsRichText |
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.
| Category | Widgets |
|---|---|
| Hero & banners | Hero, Call to action band |
| Page | Page header |
| Content | Rich text, Callout, Feature grid, Steps |
| Media | Media and text, Video |
| Social proof | Statistics, Testimonials, Logo cloud |
| Pricing | Pricing |
| Data & listings | Page listing, Article list |
| Search | Site search, Article search |
| Interactive | FAQ |
| Navigation | Site 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 insite-widgets/<Name>/<Name><Part>.tsxand 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.tsxfile 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, undercomponents/widgets, because.tsxfiles get bundled.
Form fields
The type of a field is a file name in fields/platform-fields/ or your own fields/site-fields/.
| Kind | Types |
|---|---|
| Basic | InputText, InputTextarea, InputSelect, InputRadio, InputCheckbox, InputWysiwyg, InputFile |
| From Visor’s data | InputDataSourceDropdown, InputDataSourceCheckbox, InputDataSourceSearchEngine, and others beginning InputDataSource |
| Rows | Repeatable |
Categories
Choose by what the widget does, never by brand. npm test fails on any other value.
category | categoryIcon |
|---|---|
| Hero & banners | panorama |
| Content | insert_text |
| Media | perm_media |
| Social proof | reviews |
| Pricing | sell |
| Data & listings | dataset_linked |
| Forms | dynamic_form |
| Navigation | menu |
| Page | article |
| Search | manage_search |
| Interactive | touch_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.