Listing Blocks
An editor can drop a listing of events, news, pages, products, or profiles into any rich text content. Those arrive inside the content as nodes whose attributes are that endpoint's filters — a limit, a page, tags, an ordering, and so on.
VenueContent recognises those nodes, validates the attributes, queries the endpoint, and hands the records to a component you supply. You write how a listing looks; the SDK does the fetching.
Rendering a listing
Listing components go on the same contentStyles map as your class names, keyed by the listing's node type. A string value is a class name, a function value is a listing component — no node type takes both, so the two can share one object.
import { VenueContent, getLocalizedContent } from "@venuecms/sdk-next";
import type { ContentEntries, Page } from "@venuecms/sdk-next";
// Built per request rather than kept as a module constant: a record's title
// lives on its localized content, so a listing component needs the locale the
// page is rendering in. `getLocalizedContent` is the same helper you already use
// for the page itself.
const contentStyles = (locale: string): ContentEntries => ({
p: "my-4 text-sm",
h2: "text-xl",
eventListing: ({ records }) => (
<ul className="my-8 flex flex-col gap-4">
{records.map((event) => (
<li key={event.id}>
<a href={`/events/${event.slug}`}>
{getLocalizedContent(event.localizedContent, locale).content.title}
</a>
</li>
))}
</ul>
),
});
export const PageBody = ({ page, locale }: { page: Page; locale: string }) => {
const { content } = getLocalizedContent(page.localizedContent, locale);
return (
<VenueContent content={content} contentStyles={contentStyles(locale)} />
);
};The available keys are eventListing, newsListing, pageListing, productListing, and profileListing. Leave one off and the renderer keeps whatever it would otherwise do with that node — nothing is drawn in its place.
A component is handed:
records
The records for this block's page, already fetched
site
The site, for the things a record needs it for — a timezone for a date, a currency for a price. Nullable
pagination
This block's pagination, or null. Absent from pageListing, which does not paginate
A listing component is called with its data already resolved, so it is a plain function — nothing awaits it. Use ListingProps to type one you declare separately:
Pagination
A listing paginates when its author set a page size on the block. Paging is link-based: the page lives in the URL, so the listing stays a Server Component, a page is shareable, and the back button works.
Everything on pagination is plain data — strings and numbers, no functions — so these props pass into a Client Component unchanged if you want one.
page
The current page, 0-indexed, as the endpoints index them
pageNumber
The same page, 1-based, for display
pageSize
The page size the author set on the block, capped at 100
count
Total records matching the block's filters across every page, or null when the endpoint did not report one
pageCount
How many pages that is, or null whenever count is
hasPrev / hasNext
Whether there is a page in that direction
links
Hrefs for link pagination, or null (see below)
pagination is null when the author set no page size: the endpoint returned every matching record, so there are no pages to draw.
Guard count and pageCount before displaying them. The products and profiles endpoints declare count optional, so both are null on a response that omits it. Prev/next still work in that case — hasNext falls back to "this page came back full" — but there is no total to show and no numbered pager to build, so links.hrefs is empty:
Paginating with links
Only a route segment can read search params — a listing block sits too deep in the content to ask for them — so pass them down from your page:
pagination.links is null until you do — which is how a missing searchParams prop shows up, rather than as hrefs that never move. The records and the counts arrive without it.
With search params threaded through, a prev/next pager:
prevHref and nextHref are null at the ends of the listing, so a pager renders only the directions it can actually go.
links.hrefs gives one href per page if you want a numbered pager — hrefs[0] is page 1. It is empty when there is no count to number against, so a .map over it renders nothing rather than a wrong pager:
The SDK produces hrefs, not link elements — use next/link, a plain <a>, or your own router's link. scroll={false} is worth passing on next/link: the listing usually sits mid-article, and the default is to jump to the top of the page on navigation.
Following one of these hrefs is a soft navigation. Next re-renders the server component tree and swaps in the new records — the page is not reloaded, and the rest of the article stays put.
Each href carries every other search param through untouched, so your own ?filter= survives a page change, and a second listing on the same page keeps its own page while the first one moves.
Using a Client Component
A listing component is handed data only — records, the site, and pagination that is entirely strings and numbers — so it can be a Client Component if the block needs browser state. Mark that file "use client" as usual:
The Server Component that builds contentStyles is where the two meet. A listing component takes only the props the SDK hands it, so anything else it needs — the locale here — is closed over there, in a file with no "use client" on it:
Do this rather than exporting a (locale) => Component factory from the "use client" file, the way the Server Component examples above do. Everything a "use client" module exports is a reference to something that runs in the browser, not the thing itself, so the server cannot call it — only render it. locale crosses as a prop, which is a string and serializes.
Import types from @venuecms/sdk-next freely — type-only imports erase. Do not import its values into a "use client" file: the package root carries the server-side data fetching and the credentialed SDK underneath it. Localize on the server, where getLocalizedContent runs, and pass the result down as a prop.
Notes
pageis 0-indexed everywhere, matching the endpoints.pageNumberis the 1-based one to display.countis the total match, not the size of the current page —records.lengthis the page — ornullwhere the endpoint reported no total.Each block owns its own search param, named from the listing type and a hash of its filters —
?evt_1a2b3c=2. Two listings on one page therefore page independently, and adding, removing, or reordering blocks does not shuffle the others' params. Two blocks with identical filters get an ordinal suffix (_2) to tell them apart.pageListingdoes not paginate, sopaginationis absent from its props rather than always null. A page read has to return every page for parent-path resolution.links.hrefsis capped atMAX_PAGE_LINKS(200) entries so a very large listing does not put thousands of strings on your props.pageCountstays exact, so you can tell when the list has been truncated.prevHref/nextHrefare unaffected.A listing that matched nothing renders nothing rather than an empty state — it sits mid-prose, where a "nothing found" message would read as the author's copy. A page past the end of a listing that did match still renders, so a reader who overshot gets a pager with a link back.
A page is capped at
MAX_PAGE_SIZE(100) records. An author who sets a larger page size on the block gets 100;pagination.pageSizereports the size actually used, and every record is still reachable across the pages.pageis capped atMAX_PAGE(1000). A URL asking for a deeper page clamps to it, and apageattribute on the block clamps to it.nextHrefstops there too, so a pager never offers a link that would clamp back to where it was clicked. The endpoints page by offset, so an unbounded page number is an unbounded scan; no pager a reader clicks reaches this far.countmay be absent on product and profile responses, which declare it optional. It is then reported asnullrather than guessed: the records render, prev/next still work off "was this page full", but there is no total to display andpageCount/hrefsare empty. The one cost is a next link on the last page of a listing whose length is an exact multiple of the page size — it lands on a page with no records. That page still draws, with a pager back, rather than the block disappearing from the article.The URL only overrides the author's page when it names the block. An author can start a listing on a later page via the block's own
pageattribute; passingsearchParamsdoes not reset that.?evt_1a2b3c=0does override it, since that names the block explicitly — and that is what the generated links write for such a block, so its "Previous" and its "1" reach page 0 rather than falling back to where the author started. A block whose author leftpagealone keeps the shorter first-page href, with no=0in it.A padded query string is not carried into every link. Each page href reflects the rest of the query so your own params survive pagination, but there is a budget on how much — far above any real page's query string — since one request's params otherwise multiply into every one of up to 200 hrefs per block. The budget is measured on the encoded href, so it is a bound on what gets written rather than on what arrived.
This package ships no server actions. Pagination is entirely server-rendered, and everything on
paginationis data. An action is a public HTTP endpoint whose arguments its caller supplies, so one shipped from an SDK would be an endpoint you mount without having written it; a build check fails if a"use server"ever reaches the output. If you want records appended in place rather than a page navigation, write that action in your own app, where you decide what it accepts.
Last updated

