<ContextualSite /> Provider
The root provider that coordinates domain-level data distribution to all contextual UI components. In single-page apps (SPAs), it compiles and injects the unified Schema.org JSON-LD @graph.
Wrap your root layout with ContextualSite to provide data across all components. import { siteApp } from '@/data/site.server';
import { ContextualSite, Navbar, Faq, Footer } from 'contextual-ui';
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const data = await siteApp.fetchData();
return (
<html lang="en">
<body>
<ContextualSite data={data}>
{children}
</ContextualSite>
</body>
</html>
);
}
export function SinglePageApp() {
return (
<ContextualSite schema={siteSchema} data={siteData}>
<Navbar.Root />
<main>
<Faq.Root />
</main>
<Footer.Root />
</ContextualSite>
);
}
Schema Reference & Contract
7 fields| Field | Type | Requirement | Schema.org Mapping | Description |
|---|
| data | SiteData | Required | @graph | Domain-level data object providing website, navbar, footer, and FAQ configurations. |
| data.website | WebsiteData | Optional | WebSite | Site-level metadata including name, url, and meta description. |
| data.navbar | NavbarData | Optional | SiteNavigationElement | Navigation brand and menu links automatically inferred by <Navbar.Root />. |
| data.footer | FooterData | Optional | WPFooter | Footer structure, copyright, and social links automatically inferred by <Footer.Root />. |
| data.faq | FaqItem[] | Optional | FAQPage | FAQ question-answer pairs automatically inferred by <Faq.Root />. |
| graph | ContextualGraph | Optional | @graph | Pre-compiled Schema.org JSON-LD graph produced by siteApp.getGraph(). |
| children | ReactNode | Required | — | Child components rendered within ContextualSite context. |
<WebPage /> Wrapper
The route-level React Server Component that coordinates page-level Schema.org metadata and automatically injects the canonical @graph script tag for that specific URL.
Wrap individual routes in page.tsx with WebPage from contextual-ui/server. import { siteApp } from '@/data/site.server';
import { WebPage } from 'contextual-ui/server';
import { DocsClient } from './DocsClient';
export const generateMetadata = () => siteApp.getMetadata('docs');
export default async function DocsPage() {
const data = await siteApp.fetchData();
return (
<WebPage app={siteApp} id="docs">
<DocsClient data={data} />
</WebPage>
);
}
Schema Reference & Contract
6 fields| Field | Type | Requirement | Schema.org Mapping | Description |
|---|
| app | ContextualApp | Optional | @graph | ContextualApp instance to compile and inject the route-specific Schema.org JSON-LD graph. |
| name | string | Optional | WebPage.name | Route-specific page title/name for search engines and AI agents. |
| url | string | Optional | WebPage.url | Route-specific canonical pathname (e.g. "/docs"). |
| description | string | Optional | WebPage.description | Route-specific meta description. |
| graph | JsonLdGraphResult | Optional | @graph | Pre-computed Schema.org JSON-LD graph (optional explicit override). |
| disableJsonLdScript | boolean | Optional | — | Disables script tag rendering when set to true. |
<Content /> Portable Renderer
Universal renderer for portable, CMS-agnostic content blocks (paragraphs, headings, lists, links, callouts, and code blocks) with custom component slot overrides and plain-text extraction for AI agents.
Live <Content /> DemoPortable content block rendered with automated styling and plain-text extraction:
export const content = [{ type: 'paragraph', text: 'Hello World' }];
Renders dynamic content blocks with custom Tailwind overrides. <Content
data={section.content}
components={{
paragraph: ({ children, role }) => (
<p className={role === 'qualifier' ? 'text-xs text-accent italic' : 'text-sm text-zinc-300'}>
{children}
</p>
),
code: ({ code, language }) => (
<pre className="p-4 bg-zinc-900 rounded-lg font-mono text-xs text-zinc-100">{code}</pre>
),
}}
/>
Schema Reference & Contract
3 fields| Field | Type | Requirement | Schema.org Mapping | Description |
|---|
| data | ContentInput | Required | text (extracted plain-text) | Single or array of ContentBlocks, raw markdown string, or structured Portable Text blocks. |
| components | ContentComponentOverrides | Optional | — | Custom React component slots for paragraph, heading, list, callout, code, link. |
| className | string | Optional | — | Optional CSS class name for the wrapper container. |