Widgets are the building blocks of every page in ApostropheCMS. This guide explains what they are, how to add and edit them, and what to expect from different widget types so that you can build and update pages with confidence.
Widgets are the building blocks of pages in ApostropheCMS — you assemble pages by adding and arranging them.
Widgets might be either core (built into Apostrophe) or custom.
There are two "Add Content" menus: the inline popover (a quick floating list) and the expanded widget menu (a left-side panel with visual previews organized by category).
Widget availability in a given area is controlled by your developer.
Widgets edit differently depending on how they were built. They may reference content from a shared library (piece-driven), hold their own content (inline fields), or contain other widgets inside them (area-based). The edit interface tells you which pattern you're working with.
Some widgets include a Style Editor with controls for padding, color, borders, and more — what's available is configured per widget by your developer.
When you edit a page in ApostropheCMS, you're not writing into a single big text box. Instead, you're typically assembling a page layout and content from widgets, which are individual, reusable building blocks.
A widget might be a rich text block, an image or video, a callout, a testimonial, or a pricing table. Each one has its own set of fields, its own design, and its own purpose. You place them in sequence to build a page, and you can move, edit, or remove any of them independently.
Think of widgets like LEGO bricks. The page is the model, and you decide which bricks to use and in what order.
In our public demo, for example, the homepage is made up of several widgets stacked together: a Hero at the top, followed by a Feature Grid, a Testimonial, and a CTA strip. None of those sections were hard-coded — they were each added as a widget by an editor.
Not all widgets are the same, and understanding where a widget comes from helps you know what to expect from it — and who to talk to if something needs to change.
These ship with ApostropheCMS itself. You'll find them in every Apostrophe-powered site, regardless of who built it. We consider them essential building blocks for most types of content. There are four:
Layout: creates flexible column structures, letting you place other widgets side by side. Think of it as a container that controls how content is arranged horizontally on the page.
Rich Text: formatted text with headings, links, lists, and inline styles. This is the most commonly used widget for body copy and editorial content.
Image: a single image with alt text and optional caption, pulled from your media library.
Video: an embedded video player from services like YouTube or Vimeo.
Core widgets are stable and well-documented. They can and should also be configured by developers to a website’s individual needs. The simplest example is that the rich text toolbar should be configured to your style guide and can be extended to feature additional tools.
These were built specifically for your site by your development team. They represent functionality or design patterns unique to your project — things that core widgets or the widgets that came from our demo don't cover.
Custom widgets might include things like:
A product block with image, specs, and a buy button
A widget for displaying a staff member profile
A widget that integrates with a third-party tool
If a custom widget isn't behaving as expected, or if you need a new one, your product and/or development team is the right point of contact. Unlike core widgets, custom widgets don't have public documentation, but many teams maintain internal documentation and custom knowledge bases.
Hero: a large section featuring a headline, subheadline, and CTA buttons
Feature Grid: a multi-column layout for product features or benefits
Testimonial: a quote with attribution, optional title or description and optional headshot or logo
Pricing Table: a comparison layout for plans or tiers
When you're editing a page in context (meaning: viewing the actual page while in edit mode), you'll see + Add Content buttons appear on dashed lines between sections. Clicking one opens a menu where you choose which widget to add.
There are two different styles of menus that open from the “Add Content” button, and which menu opens is a decision made by the team responsible for your website development.
In some areas, clicking + Add Content opens a small floating popover right where you clicked. It shows a short list of available widgets, each with a small icon and a name.
When you'll see it: In structured areas of the page where only a limited set of widgets is available, and the choices are simple enough that a preview isn't needed (ie. “rich text” or “image”). On the demo site, you'll see this in areas like the hero section, where only a Rich Text widget can be added.
Click + Add Content on the dashed line where you want to insert a widget
The popover appears — click the widget name you want
The widget is added and its edit modal opens
This menu is designed for speed in very straightforward parts of your layout. If you see it, there aren't many choices to make.
In other areas, clicking + Add Content opens a panel that slides in from the left side of the screen like a drawer. We call this our “Expanded widget menu.” Unlike the simple inline popover, the drawer shows a visual preview of each widget, along with its name and a one-line description. This can be really helpful when working on page with a lot of widget options, because naming is notoriously difficult and many of us find it easier to quickly grasp what something does with a visual.
Widgets in the drawer are organized into categories. On the demo site you'll see groups like Layout Tools, Media, and Elements, which makes it easier to find what you're looking for when there are many options. These categories are also configurable by the team who built and/or updates your website.
When you'll see it: In open, flexible content areas where many widget types are available. On the demo site, the main content area of most pages uses the drawer.
How to use it:
Click + Add Content on the dashed line where you want to insert a widget
The drawer slides open from the left — browse by category or scan the previews
Click the widget you want
Its edit form opens
The drawer is especially useful when you're not sure which widget fits — the visual previews let you see what each one looks like before you commit.
Not every widget is available in every area. The product or development team responsible for your website configures which widgets can appear in which parts of a page, and this is intentional. It prevents, for example, a full-width Hero widget from being dropped into a narrow sidebar.
If you open a content menu and don't see a widget you're expecting, it may be restricted in that area by design. Check with your developer before assuming something is missing.
Once a widget is on the page, hover over it in edit mode and you'll see a small toolbar appear with options to edit, move, delete or duplicate the widget. If the widget was designed to be edited in context, you can click on the text and begin editing. Save the draft or update when you're done.
If the fields are not editable in context, click the pencil icon to open the widget editor modal and make you updates.
You may notice that editing of content in widgets isn't always done the same way: Sometimes you can click directly on text in the page and change it on the spot. Other times, clicking a widget opens a separate form. And occasionally, a widget contains other widgets inside it that each have their own editing experience.
This is a deliberate choice developers made when building each widget, and the different editing techniques fall into three main patterns.
In this pattern, the widget pulls in content that lives elsewhere, such as a piece (aka “content type”), allowing the same content to be reused across multiple pages without having to re-enter it multiple times. As an editor, you're selecting which items to display, not creating or editing them inside the widget.
Example: Imagine a Testimonials widget on the homepage. Your developer might have built the widget to reference a Testimonials library, a central place where each testimonial (quote, author name, headshot, company) is stored and maintained.
When you place the widget on a page, you choose which testimonial(s) to show. The actual testimonial content (the quote, photo, name, title or role) is managed in a different part of the ApostropheCMS admin. Your main menu might have a top-level item called “Content” and under that, you might find “Testimonials.” This architecture is up to the team who customized the CMS with your individual editing experience and use cases in mind.
What editing looks like: Clicking to edit opens a form where you select or search for items from the library. You won't see the content itself inline on the page — you're making a selection.
Why developers build it this way: When the same testimonial appears on multiple pages, it only needs to be updated once in the library. Every widget that references it updates automatically. It also ensures consistency, so the same headshot and bio appear everywhere, without risk of one-off edits creating discrepancies. Imagine having to change the role or position of someone: Rather than find and update every instance, you would change it in one place.
The tradeoff for editors: You can't edit a testimonial's content from inside the widget to cater to a specific layout or page. If something needs changing, you'll need to find it in the Testimonials library and update it there.
In this pattern, the widget contains all of its own content directly. There's no shared library, and everything you see on the page lives inside that specific widget instance. Two Testimonials widgets placed on two different pages would have completely independent content.
Example: A Testimonials widget built this way would have fields directly inside it: a text field for the quote, an image field for the headshot, a text field for the author name. You fill those in when you place the widget, and that content exists only in that widget on that page.
What editing looks like: Clicking to edit opens a form with the actual fields. You're typing and uploading directly into the widget. Changes only affect this instance.
Why developers build it this way: It's simpler when content won't be reused elsewhere. A one-off quote on a specific landing page doesn't need to live in a shared library.
The tradeoff for editors: If the same testimonial appears in multiple places and the person's title changes, you'd need to update each widget individually. There's no central source of truth.
In this pattern, a widget acts as a container, providing structure (a layout, a background, a column arrangement) but the content inside it is made up of other widgets that you add and edit independently.
Example: A hero widget with a layout widget set to two columns, background color options, a text field for the heading, an embedded rich text widget for the description or subheading, and an Image widget. Each of those inner widgets is edited on its own.
What editing looks like: The outer Hero widget may have a few settings (background color, for example), but most of the editing happens inside it. You'll see the familiar + Add Content button appear within the widget, and you add and edit inner widgets just as you would anywhere else on the page.
Why developers build it this way: It gives editors maximum flexibility within a controlled structure and design. The developer defines the container; the editor decides what goes inside it.
The tradeoff for editors: More flexibility means more decisions. It also means more steps.
You often can't tell from looking at a page which pattern a widget uses; all three can produce identical visual results. The clearest signal is what happens when you click to edit:
A selection or search interface is a piece-driven widget (Pattern 1)
A form with specific fields is an inline fields widget (Pattern 2)
An + Add Content button inside the widget means it's a nested widget (Pattern 3)
If you're ever unsure why a widget behaves the way it does, or want to request a change to how content is managed, your developer can explain which pattern was used and what it would take to change it.
Some widgets on your site may include a Style Editor, an additional set of controls that lets you change how a widget looks without touching any code. If your site has it enabled, you'll see a style panel when you open a widget to edit it.
The styles available in the Styles Editor depends entirely on what your developer has configured for each widget.
Not every widget will have all of these options, and some widgets may have none at all. The Style Editor only surfaces controls that your developer has explicitly made available — it's a curated set of choices, not an open canvas.
What this means in practice: If you're placing a Testimonials widget and want it to sit on a dark background, you might be able to set that directly in the Style Editor without asking your developer. But if the background color option isn't there, that styling is either fixed by design or hasn't been configured yet — again, a conversation for the dev team.
