API Reference

Config Builders Metadata Helpers Robots Helpers Open Graph & Twitter Schema Generators React Components Utilities TypeScript Types

Config Builders

Functions for creating, merging, and normalizing SEO configuration objects.

`createSEOConfig(config?)`

Creates a normalized SEO configuration object. Trims strings, normalizes URLs, and removes empty values.

import { createSEOConfig } from "react-ssr-seo";

const config = createSEOConfig({
  titleTemplate: "%s | My Site",
  description: "My site description.",
  openGraph: { siteName: "My Site", type: "website" },
  twitter: { card: "summary_large_image", site: "@mysite" },
});

`mergeSEOConfig(base, override)`

Deep-merges two SEO configs. The override's values take precedence. Arrays are replaced, not concatenated.

import { mergeSEOConfig } from "react-ssr-seo";

const pageConfig = mergeSEOConfig(siteConfig, {
  title: "About",
  description: "About our company.",
  openGraph: { title: "About Us" },
});
// siteConfig's twitter, titleTemplate etc. are preserved
// openGraph is deep-merged (siteName from base + title from override)

`normalizeSEOConfig(config)`

Trims all string values, normalizes URLs (removes trailing slashes), and removes empty/undefined fields. Called internally by createSEOConfig.

Metadata Helpers

Function	Description	Example
`buildTitle(title, template?)`	Applies title template	`buildTitle("About", "%s \| Site")` → `"About \| Site"`
`buildDescription(desc, maxLen?)`	Truncates with ellipsis (default 160 chars)	`buildDescription("Long text...", 100)`
`buildCanonicalUrl(base, path)`	Combines base URL + path	`buildCanonicalUrl("https://site.com", "/about")`
`buildAlternateLinks(alternates)`	Builds hreflang link tag data	`buildAlternateLinks([{ hreflang: "en", href: "..." }])`

Robots Helpers

Function	Returns	Renders As
`buildRobotsDirectives(config)`	Robots content string	`"index, follow"` (or custom)
`noIndex()`	`{ index: false, follow: true }`	`"noindex, follow"`
`noIndexNoFollow()`	`{ index: false, follow: false }`	`"noindex, nofollow"`

RobotsConfig typeTypeScript

interface RobotsConfig {
  index?: boolean;        // default: true
  follow?: boolean;       // default: true
  noarchive?: boolean;
  nosnippet?: boolean;
  noimageindex?: boolean;
  notranslate?: boolean;
  maxSnippet?: number;           // max-snippet:N
  maxImagePreview?: string;      // max-image-preview:value
  maxVideoPreview?: number;      // max-video-preview:N
}

Open Graph & Twitter

`buildOpenGraph(config)`

Builds an array of Open Graph meta tag objects from an OpenGraphConfig.

const ogTags = buildOpenGraph({
  title: "My Page",
  description: "Page description.",
  url: "https://mysite.com/page",
  siteName: "My Site",
  type: "article",
  locale: "en_US",
  images: [{
    url: "https://mysite.com/image.jpg",
    width: 1200,
    height: 630,
    alt: "Page image",
  }],
});
// Returns array of { property, content } objects

`buildTwitterMetadata(config)`

Builds an array of Twitter Card meta tag objects.

const twitterTags = buildTwitterMetadata({
  card: "summary_large_image",
  site: "@mysite",
  creator: "@author",
  title: "My Page",
  description: "Page description.",
  image: "https://mysite.com/image.jpg",
  imageAlt: "Description of image",
});
// Returns array of { name, content } objects

JSON-LD Schema Generators

All generators return plain objects with @context: "https://schema.org". Use with the <JsonLd> component or safeJsonLdSerialize().

Function	Schema Type	Key Inputs
`createOrganizationSchema(input)`	Organization	name, url, logo, sameAs, contactPoint
`createWebsiteSchema(input)`	WebSite	name, url, description, searchUrl
`createArticleSchema(input)`	Article	headline, url, datePublished, author, publisher, images
`createProductSchema(input)`	Product	name, url, price, priceCurrency, brand, sku, availability
`createBreadcrumbSchema(items)`	BreadcrumbList	Array of { name, url }
`createFAQSchema(items)`	FAQPage	Array of { question, answer }
`composeSchemas(...schemas)`	@graph	Multiple schema objects → single @graph array

Composing multiple schemasTypeScript

import {
  createOrganizationSchema,
  createWebsiteSchema,
  composeSchemas,
  JsonLd,
} from "react-ssr-seo";

const org = createOrganizationSchema({ name: "My Co", url: "..." });
const site = createWebsiteSchema({ name: "My Site", url: "..." });

// Combine into a single <script> tag with @graph
const composed = composeSchemas(org, site);

<JsonLd data={composed} />
// Renders: { "@context": "...", "@graph": [org, site] }

React Components

`<SEOHead {...config} />`

SSR-safe component that renders all SEO tags as React elements inside <head>. Renders <title>, <meta>, <link> tags for title, description, canonical, robots, Open Graph, Twitter, hreflang, and any additional meta/link tags.

import { SEOHead, mergeSEOConfig } from "react-ssr-seo";

const seo = mergeSEOConfig(siteConfig, { title: "My Page" });

<head>
  <meta charSet="utf-8" />
  <SEOHead {...seo} />
  {/* Renders: <title>, <meta>, <link> tags */}
</head>

Props: All SEOConfig fields plus an optional nonce string for Content Security Policy support on JSON-LD script tags.

`<JsonLd data={schema} nonce? />`

Renders a single <script type="application/ld+json"> tag with safely serialized JSON-LD data. Uses safeJsonLdSerialize internally to escape HTML-breaking characters.

import { JsonLd, createArticleSchema } from "react-ssr-seo";

const schema = createArticleSchema({
  headline: "My Post",
  url: "https://mysite.com/post",
  datePublished: "2025-01-01",
  author: [{ name: "Author" }],
});

<head>
  <JsonLd data={schema} />
  {/* Renders: <script type="application/ld+json">...</script> */}
</head>

Utilities

Function	Description
`safeJsonLdSerialize(data)`	Serializes data to JSON and escapes HTML-breaking characters (<, >, &) for safe embedding in <script> tags
`omitEmpty(obj)`	Removes undefined, null, and empty string values from an object
`deepMerge(base, override)`	Recursively merges two objects. Arrays in override replace base arrays
`normalizeUrl(url)`	Trims whitespace and removes trailing slashes from a URL
`buildFullUrl(base, path)`	Alias for `buildCanonicalUrl` — combines base URL with a path

TypeScript Types

All types are exported from the main entry point. Import what you need for type annotations.

Available type exportsTypeScript

import type {
  // Main config
  SEOConfig,

  // Sub-configs
  OpenGraphConfig,
  OpenGraphImage,
  TwitterConfig,
  RobotsConfig,
  AlternateLink,

  // Schema inputs
  OrganizationSchemaInput,
  WebsiteSchemaInput,
  ArticleSchemaInput,
  ProductSchemaInput,
  FAQItem,
  BreadcrumbItem,
} from "react-ssr-seo";

SEOConfig — main configuration typeTypeScript

interface SEOConfig {
  title?: string;
  titleTemplate?: string;        // "%s | Site Name"
  description?: string;
  canonical?: string;
  robots?: RobotsConfig;
  openGraph?: OpenGraphConfig;
  twitter?: TwitterConfig;
  alternates?: AlternateLink[];  // hreflang links
  additionalMetaTags?: Array<{
    name?: string;
    property?: string;
    content: string;
  }>;
  additionalLinkTags?: Array<{
    rel: string;
    href: string;
    hreflang?: string;
    type?: string;
    sizes?: string;
  }>;
  jsonLd?: Record<string, unknown>
    | Array<Record<string, unknown>>;
}

Import Paths

Three entry points for tree-shaking optimization.

Import	Contents	Use Case
`"react-ssr-seo"`	Everything	Default — all types, builders, schemas, components
`"react-ssr-seo/schema"`	Schema generators only	Lightweight import when you only need JSON-LD
`"react-ssr-seo/components"`	React components only	When you only need SEOHead and JsonLd

VIEW

This page also has SEO tags. Right-click → View Page Source to see the meta tags generated for this API Reference page.

Contents

Config Builders

createSEOConfig(config?)

mergeSEOConfig(base, override)

normalizeSEOConfig(config)

Metadata Helpers

Robots Helpers

Open Graph & Twitter

buildOpenGraph(config)

buildTwitterMetadata(config)

JSON-LD Schema Generators

React Components

<SEOHead {...config} />

<JsonLd data={schema} nonce? />

Utilities

TypeScript Types

Import Paths

`createSEOConfig(config?)`

`mergeSEOConfig(base, override)`

`normalizeSEOConfig(config)`

`buildOpenGraph(config)`

`buildTwitterMetadata(config)`

`<SEOHead {...config} />`

`<JsonLd data={schema} nonce? />`