Widgets and sidebars

Appearance → Widgets (/admin/widgets) shows every widget area at once. The palette of widgets is on the left; each area is on the right as a list of widgets you can expand to edit. A widget area is a named slot of blocks shown next to the page content: the blog sidebar, a filter column on the shop page, or a strip above an article.

Fill an area#

1. 1

   Drag a widget in

   Drag a widget from the palette onto an area, and drag widgets within an area to reorder them.

2. 2

   Edit its settings

   Expand a widget to change its title, menu, number of posts, and the rest.

3. 3

   Save a draft, then publish

   An area keeps a draft next to the live version, like the footer. Visitors see the change once you publish.

4. 4

   Translate

   The widgets in an area show in every language. Replace them for one language when that language needs different widgets.

Where an area shows#

The Layout tab chooses, per content type, which area shows and where: left, right, or top (above the content). A content type without a choice uses the first area that lists it as a default. On a single page the content comes first in the HTML and the <aside> after it; CSS places the area. A template that places the Widget area block (core.widget-area) itself controls its own layout and is left alone.

Width and spacing#

Styles → Layout sets the sidebar width and the gap between the content and the sidebar, for the whole site or per layout target, the same way as the content width. One area can also have its own width (160–640 px) on the Widgets page. The layout CSS sits at the top of /theme.css inside :where(), so every theme rule wins over it.

Areas of your own#

Core ships one area, sidebar. Add widget area creates another, with a key, a label, and an optional description; areas you add can be deleted again. Areas from the theme and from plugins stay as long as that theme or plugin is active. Deactivating a plugin removes its area from the public site, but the widgets you saved in it are kept.

For theme authors#

Declare areas in justflows-theme.json and ship their starting widgets in widgets/<key>.json. Keys are lowercase letters, digits, and dashes, at most 32 characters. Declaring sidebar relabels the core sidebar. An area the site owner has never saved shows the theme's default; a saved empty area shows nothing.

"widgetAreas": {
  "sidebar": { "label": "Blog sidebar" },
  "footer-1": { "label": "Footer column", "description": "Left footer column" }
}

For plugin authors#

Add an area with the widgets.areas filter, with optional default widgets and the content types that show it until the owner chooses otherwise. Widgets are ordinary blocks registered with category: "widgets". The widgets plugin API namespace is reserved for core.

ctx.hooks.filter("widgets.areas", (areas) => [
  ...areas,
  {
    key: "acme-events",
    label: "Events sidebar",
    defaultBlocks: [{ id: "upcoming", type: "acme.events.upcoming", version: 1, props: {} }],
    defaultLayout: { contentTypes: ["event"], position: "right" },
  },
]);

API and AI agents#

MCP tools: widget_areas_list, widget_areas_get, widget_areas_create, widget_areas_update, widget_areas_delete, widget_areas_discard_draft, and widget_layout_update.