Builder & design · guide

Widgets and blocks

Every built-in widget, when to use each, and how to build your own.

Widgets and blocks

Widgets are the building blocks of every page. WordSafe ships 60+ out of the box.

Layout widgets

Widget	Use for
Section	Full-width horizontal band with a background
Container	Constrain width, apply padding
Columns	1–6 columns with per-breakpoint stack order
Grid	CSS grid with named areas
Spacer	Precise vertical whitespace

Content widgets

Heading, paragraph, list, image, button, icon, divider, quote, code block, embed.

Marketing widgets

Testimonial, pricing table, feature grid, CTA banner, stats counter, logo cloud, FAQ accordion.

Dynamic widgets

Post loop, related posts, categories list, breadcrumbs, search — all wired to the CMS. Use in archive templates.

Form widgets

Contact form, booking form, newsletter opt-in, quote request. All submissions flow to Forms → Submissions and can trigger CRM automations.

Custom widgets

Create your own with a React component and a schema:

// widgets/callout.tsx
import { defineWidget } from "@wordsafe/builder";

export default defineWidget({
  name: "callout",
  label: "Callout",
  schema: {
    heading: { type: "text", default: "Heads up" },
    tone:    { type: "select", options: ["info", "warn", "success"], default: "info" },
  },
  render: ({ heading, tone }) => (
    <div className={`callout callout--${tone}`}>{heading}</div>
  ),
});

Drop it in src/widgets/, run bun run widgets:register, and it appears in the Widget library.