How a Sanity page builder works
The page builder field is a reorderable container that holds all the content blocks, either object types or reference types. Blocks modeled as inline objects are simpler to query, but they cannot be reused outside the document that contains them. Blocks modeled as references can be reused across documents, and queries have to resolve those references.
A GROQ query over a page builder array often needs different fields per block type, plus reference resolution for referenced blocks. The frontend renders each block by switching on the item's _type value to pick the matching component. Every block carries a _key that is unique within the array, and React code can use it as the key prop. Sanity's guide to structured content for page building covers these modeling choices in more detail.
Design rules and editor features
Sanity recommends modeling page builder blocks by what the content means, leaving colors and layout to frontend code. Sanity estimates that a 100-page marketing site usually needs 12 to 18 distinct section types. For content with a fixed formula, such as blog posts, Sanity advises against a page builder.
Grouped insert menu. The array field's
insertMenuoption can group block types so editors find related modules faster.Type search. The
insertMenufilter defaults to the'auto'value, which turns on a type search once an array allows more than five types.Grid view. The
viewsoption switches between a list menu and a grid view that can show a preview image per block type.
In the Presentation Tool, array fields can be set up for drag-and-drop reordering on the page, vertically or horizontally (see Sanity Visual Editing). The setup needs data-sanity attributes built with createDataAttribute from the next-sanity package, using the source document's ID and type. The useOptimistic hook in next-sanity updates reordered blocks on the page immediately. If one Sanity project serves several sites, read how to manage multiple websites from one Sanity instance.
How Pagepro builds Sanity page builders
Pagepro builds its Sanity development projects on Nexity, its delivery system for migrating legacy web stacks to Next.js and Sanity on Vercel. Nexity ships more than 30 pre-built content blocks and a Page document type that works as the builder. Its featured, related and latest blocks each have a manual-input variant, so editors can place any page in those slots, beyond the newest posts.
Sources
- Course: Build landing pages with Next.js (Sanity Learn)Sanity · sanity.io
- How to use structured content for page buildingSanity · sanity.io
- Build a page builder with a sections array (Sanity Learn)Sanity · sanity.io
- Array typeSanity · sanity.io
- Preview and page buildingSanity · sanity.io