Themes

Admin → Themes. Upload a .jfpkg or zip (POST /api/themes, administrator). Activate with POST /api/themes/:id/activate. List from GET /api/themes. Hooks: theme.installed, theme.activated. Admin → Themes also lists every published theme from the hosted Marketplace, with installed, paid, and coming-soon states; community themes install through the same signed-package flow, and inactive installed themes can be deleted (the active and bundled themes are protected).

Every folder under themes/ is registered in the themes table automatically the first time the admin themes or customizer screen loads — previously only justflows.default was seeded, so a bundled or dropped-in theme is now selectable without a .jfpkg upload. syncBundledThemes also refreshes an existing row's name, version, and manifest from the folder while leaving its status, activated_at, and css_variables as the admin left them. The bundled starter is `justflows.default` under themes/default (templates, styles, patterns, justflows-theme.json).

Marketplace themes update the same way as plugins: Themes shows Update available with an Update to vX button, and each theme has an Auto-update switch that stays within the same major version (see Plugins). Save as new theme writes the fork to the site's own folder, packages-installed/sites/<siteId>/themes/local.<slug>/. Forks saved earlier keep working, and deleting a fork removes its folder.

Marketplace themes include Halden, a clean clothing-store theme with collection tiles, a lookbook, and product styling for Shop, and Zine, a playful blog and news theme with sticker-style cards, terminal-style code blocks, and a full dark mode. Browse them all on the Marketplace.

Patterns#

GET /api/themes/patterns and GET /api/themes/patterns/:slug feed the block editor. Patterns are starter block trees, not separate post types. A pattern can declare requiresBlockTypes; if an active plugin does not provide a required block, its card explains what is missing and links to Extensions instead of importing broken content. patterns/product.json and patterns/post.json also double as the starting canvas for a new product or post whose editor opens empty, matched by an explicit type allowlist (defaultBlocksForContentType). The default theme includes a Contact pattern that uses the Forms block.

Theme builder#

• Home — choose any published page for /, or turn the active theme's current home layout into an editable page.
• Blog — choose any page as the blog index, or create one from the theme default. Add Post List to build a custom paginated index.
• Footer — edit the shared site footer as blocks, keep a draft, and publish it. Sites without a custom footer fall back to the theme's demo/footer.json.
• Header — keep a library of named headers; one is the site default and renders on every page. Each page picks its header — the site default, a named header, or *None* — from the page builder.
• Templates — edit any template in the hierarchy (index, front-page, single, page, 404, …) visually; edits save per site with draft / publish / reset.

Template hierarchy#

Themes own page structure through a WordPress-style template hierarchy — one JSON block document per slot under templates/, shared chrome under parts/, and a visual editor at Theme builder → Templates. See Templates.

Theme-shipped site chrome#

A theme can ship default chrome that is resolved live at render, the same way demo/home.json provides a home layout. demo/footer.json is a block document — Theme builder → Footer seeds its canvas from it and GET /api/template-parts/footer returns fromThemeDefault. demo/header.json is a sparse PageHeaderConfig merged over the built-in default, used when the header library has no default entry. Nothing is written to the database on activation; an admin edit always wins.

The visual menu designer adds front-end the default theme ships: the partials/nav-menu.ejs renderer, /js/site-nav.js (desktop flyouts, an off-canvas mobile drawer, keyboard navigation, prefers-reduced-motion), and the .jf-nav styles in global.css. The shared data-jf-devices CSS primitive for per-device visibility is emitted into every theme's /theme.css. Themes contribute menu layout presets through the menu.design.presets filter.

Widget areas#

A theme can declare its own sidebars and columns under widgetAreas in justflows-theme.json, with starting widgets in widgets/<key>.json, or place the Widget area block in a template. Site owners fill them under Appearance → Widgets. See Widgets and sidebars.

Theme-contributed controls#

A customize block in justflows-theme.json adds the theme's own Customizer sections and controls (color, range, select, font, each keyed by the CSS custom property it sets), and a blockControls map promotes chosen theme variables to first-class fields in the block inspector. See Theme customizer and Block editor.