BizzPocket

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()

tsx
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

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, nofollow on every page. A filtered or sorted listing is noindex, follow. Cart, checkout, account and order pages are noindex, nofollow; search is noindex, follow; the rest are index, follow. A block can add noindex or nofollow; index: true is 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 @type plus @id or url. Between two blocks the first wins; a block entry replaces a page default with the same type and id.

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) runs head() with the page's data in hand and replaces the old title and description tags.
  • The Next storefront runs head() from generateMetadata, 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 seconds head() 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.

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.