Type-safe React components for Schema.org JSON-LD, rich-result helpers, and linked @graph documents. Use them in any React application, including Next.js, without a Next.js dependency.
Documentation · Getting started · API reference · Examples · Issues
Created by Ryan Hefner and Commune Software.
npm install react-structuredUse an existing React 16.14 or newer application. TypeScript declarations are included, with Schema.org types powered by schema-dts. Both ESM and CommonJS entry points are available.
Render structured data alongside the visible page content. This example returns a complete React component; replace its example values with facts about your site.
import { Schema } from 'react-structured'
export default function AboutPage() {
return (
<main>
<Schema
id="organization-jsonld"
type="Organization"
data={{
name: 'Acme Studio',
url: 'https://example.com',
}}
/>
<h1>About Acme Studio</h1>
<p>We build useful software.</p>
</main>
)
}Schema emits an application/ld+json script with @context and the selected @type. It does not render visible content or fetch data. Inspect the initial HTML or rendered DOM to verify the script, and validate the data for your intended search feature. Valid Schema.org markup does not guarantee a search engine will show rich results.
| Component | Use it for | Guide |
|---|---|---|
Schema |
One Schema.org entity with inferred SchemaData<'Type'> |
Typed schema examples |
Graph |
Related entities connected by stable @id references |
Graph documents |
JsonLd |
A complete document that already includes @context |
Raw JSON-LD |
| Rich-result helpers | ArticleJsonLd, BreadcrumbJsonLd, FAQJsonLd, OrganizationJsonLd, and ProductJsonLd |
Rich-result helpers |
Schema supports every Schema.org Thing type represented by schema-dts; Graph supports its JSON-LD graph documents. TypeScript checks the selected data shape and any explicit top-level @type. Use SchemaData, GraphData, or JsonLdData when defining reusable data outside JSX.
Development-time warnings highlight missing fields for selected rich-result helpers. They are guidance, not a complete validator or a promise of eligibility. See the API reference for props and behavior.
Next.js App Router pages and layouts can render these components directly on the server; a client boundary is not required. With Pages Router, render them alongside page content. Do not nest a react-structured component inside next/head or a PageMeta component.
Use next-meta or native Next.js metadata for titles, canonical URLs, Open Graph, and social cards. Use react-structured alongside it for JSON-LD. Reuse the same absolute canonical and media URLs in both outputs, and avoid emitting the same entity twice.
Follow the Next.js guide for complete App Router and Pages Router examples. Other React applications need no Next.js package.
All rendering components accept id, nonce, scriptKey, and validate:
- Use a document-unique
idto inspect the script. IDs do not deduplicate scripts; render each entity once. - Pass your application's CSP
noncewhen required. The library does not generate or distribute nonces. - React reserves
keyfor component identity.scriptKeycontrols the underlying script's React key, not its DOM ID. validatecontrols development-time rich-result warnings and defaults totrue.
The library escapes JSON-LD script content, including </script> sequences. Escaping prevents script breakout; it does not establish that user-supplied data is accurate or appropriate to publish. Model the visible page honestly, keep private data out of JSON-LD, and read the security guide.
Open an issue, browse the documentation, or see the source and tests. Report security concerns privately to the maintainer rather than a public issue.
Repository development uses the pinned Node 24 and pnpm versions. These pins do not change the library's React peer compatibility or require consumers to use pnpm.
nvm use
corepack enable
pnpm install --frozen-lockfile
pnpm run verify
pnpm run buildThe documentation site is published at react-structured.dev. Run pnpm run docs:dev locally; see docs development and deployment for the independent site checks and Vercel configuration. Package verification intentionally does not require docs workspace dependencies.
Coverage is generated with pnpm run test:ci. Publishing uses npm trusted publishing; package publishing and documentation deployment remain separate operations.