Search and sharing tags: head()
On this page
A block can set the page's title, description, canonical link, share image and structured data by
exporting a head() function. The platform merges the answers of every block on the page, adds what it
knows about the page itself, and writes the tags. You do not write <title> or <meta> by hand.
A block with no head() changes nothing: a page where no block has head() gets exactly the tags the
store already emitted.
Write a head()
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'About hero',
category: 'content',
fields: {
heading: f.text({ default: 'Our story' }),
intro: f.text({ default: 'Handmade in small batches.', multiline: true }),
picture: f.image(),
},
head: (p, ctx) => ({
title: p.heading,
description: p.intro,
image: p.picture ? { src: p.picture.src, alt: p.picture.alt } : undefined,
jsonLd: { '@context': 'https://schema.org', '@type': 'AboutPage', name: p.heading, url: ctx.store.origin },
}),
render: ({ heading, intro }) => (
<section>
<h1>{heading}</h1>
<p>{intro}</p>
</section>
),
});head(props, ctx) gets the block's props, including what data() loaded, and a HeadContext:
store (slug, name, origin), route, pageType, locale, dir, and the translator t and
formatters format that render has (see Translations).
It returns HeadTags or undefined:
| Key | Meaning |
|---|---|
title |
The page title. The theme's seo.titleTemplate is applied after. |
description |
The meta description. |
canonical |
A path on this store, or a URL on the store's own origin. Anything else is dropped. |
robots |
{ index?, follow? }. It can only tighten what the platform decided. |
image |
{ src, alt?, width?, height? }: the share image (og:image, twitter:image). https: or root-relative. |
og |
{ type: 'website' | 'article' | 'product' }. |
twitter |
{ card: 'summary' | 'summary_large_image' }. |
jsonLd |
One structured-data object or a list of them. |
Put head() on a block that does not wait for shopper data. A head() that throws is skipped; the page
still renders.
Site-wide defaults: seo in theme.config.ts
theme({
// ...
seo: { titleTemplate: '%s | {store}', twitterSite: '@mystore', defaultImage: '/og.png', organization: true },
});titleTemplate wraps every title, twitterSite fills twitter:site, defaultImage is the share image
when nothing else sets one, and organization: true adds an Organization JSON-LD entry on the home page.
Which answer wins
Layers, lowest first: the seo defaults, the page's own defaults (the product's SEO title and
description, the store name on the home page), then each block's head() in layout order.
- Title, description, canonical,
og:type, Twitter card: the first block in layout order that sets a valid value wins. No block set it: the page default. A rejected value (a canonical on another origin) does not count as set, so the next block can still supply one. - Robots: the platform decides first. A store that is not public is
noindex, nofollowon every page. A filtered or sorted listing isnoindex, follow. Cart, checkout, account and order pages arenoindex, nofollow; search isnoindex, follow; the rest areindex, follow. A block can addnoindexornofollow;index: trueis ignored. Any tightening wins, whatever the order. - Share images: the blocks' images in layout order, then the default image, without repeats, at most 4. The first is the main one.
- JSON-LD: entries are joined and de-duplicated by
@typeplus@idorurl. Between two blocks the first wins; a block entry replaces a page default with the same type and id.
The canonical link
The canonical is built from the store's own origin and the page path. Only page (when above 1) is kept:
tracking parameters, filters and sort are dropped, and a filtered listing points at the clean listing.
Listing pages 2 and up get a " - Page N" title suffix and a "Page N: " description prefix. Without a valid
store origin, no canonical is written.
When the store has more than one locale, hreflang alternates (and x-default) are written too.
Structured data without duplicates
Blocks used to render JSON-LD in the body with the kit's JsonLd. A block that returns JSON-LD from
head() must not also render it. Move the payload into head(). While the body must keep it, wrap it so
it skips itself when the head already carries it: JsonLd does this by default (dedupe), and
isJsonLdInRenderedHead(payload) from @bizzpocket/theme-sdk/v3 answers the same question for your own
code. bizzpocket check reports seo/duplicate-jsonld and seo/body-jsonld-duplicate.
Limits and safety
- Title 120 characters, description 320, image alt 200, 4 images, 8 JSON-LD entries of at most 32,000 characters each. Longer text is cut.
- Every value is text. Control characters are removed and whitespace is collapsed. URLs must be safe
(see limits). JSON-LD is escaped so it cannot close the
<script>.
Where it runs, and what it can see
- The Bun runtime (
bizzpocket dev, and stores served by it) runshead()with the page's data in hand and replaces the old title and description tags. - The Next storefront runs
head()fromgenerateMetadata, before the page body is built.- A block whose
data()is static (data: (p) => ({ product: product({ handle: p.handle }) })) gets its public data as well as its props and the route. The storefront resolves those needs with a head-only client that has no shopper session, once per request, and the page render reuses the answers (the product page uses the product it already loaded), so a need is not fetched twice. Slow or failing data never holds the page: after a few secondshead()runs on props and route only, and the page is marked as incomplete (not cached as a normal page). - A block that uses
load()(free-form), or whose data is shopper-scoped (customer(),orders(), and the like), gets props and the route only; a shopper-scoped block makes the head private and contributes no tags. The head is built only from public data, so it is the same for every visitor of a URL. - The route carries the path values only (no
?q=,?page=or?sort=). - A block's own head tags are not added for a page that read shopper data (the page is private). Its title, description and Open Graph win over the storefront's own; its robots can only be stricter; its canonical is used only when it is on the store's origin. Test the tags in both runtimes.
- A block whose
Check it
bizzpocket check has seo/* rules: seo/missing-title, seo/conflicting-head, seo/canonical-rejected,
seo/image-rejected, seo/duplicate-jsonld, seo/body-jsonld-duplicate and seo/head-on-runtime-block.
They are listed in the CLI reference.