The AI-native SEO library for React. Intent-based API, self-documenting types, built for agents.
npm install react-headgear> The AI-native SEO library for React. Gear up your document head.


react-headgear is a modern SEO library for React SPAs with:
- Self-documenting types - Rich JSDoc that AI agents can read
- Introspection API - describe(), validate(), preview() for programmatic discovery
- Schema builders - Typed JSON-LD generation for structured data
- Zero dependencies - Just React as a peer dependency
``bash`
npm install react-headgear
`typescript
import { useHeadgear } from 'react-headgear';
import { Product } from 'react-headgear/schema';
function ProductPage({ product }) {
useHeadgear({
title: ${product.name} | My Store,https://mystore.com/products/${product.slug}
description: product.description,
canonical: ,
og: {
type: 'product',
image: product.image,
},
schema: Product({
name: product.name,
price: product.price,
currency: 'USD',
image: product.image,
}),
});
return
Features
$3
`typescript
useHeadgear({
title: 'Page Title',
description: 'Page description for search results',
canonical: 'https://example.com/page',
noindex: false,
keywords: ['react', 'seo'],
og: {
type: 'website',
image: '/og-image.png',
siteName: 'My Site',
},
twitter: {
card: 'summary_large_image',
site: '@myhandle',
},
});
`$3
`typescript
import { Product, Article, BreadcrumbList, FAQPage } from 'react-headgear/schema';// Product
Product({
name: 'Widget Pro',
price: 29.99,
currency: 'USD',
brand: 'Acme',
image: '/widget.png',
});
// Article
Article({
headline: 'How to Use react-headgear',
datePublished: '2025-01-15',
author: { name: 'Jane Doe' },
});
// Breadcrumbs
BreadcrumbList([
{ name: 'Home', url: '/' },
{ name: 'Products', url: '/products' },
{ name: 'Widget Pro' },
]);
// FAQ
FAQPage([
{ question: 'What is react-headgear?', answer: 'An AI-native SEO library.' },
]);
`$3
For AI agents and programmatic use:
`typescript
import { describe, validate, preview, listPresets } from 'react-headgear';// Discover preset requirements
const spec = describe('ecommerce.productPage');
// { required: ['name', 'price'], optional: [...], example: {...} }
// Validate config before applying
const result = validate(config);
// { valid: false, errors: [...], warnings: [...] }
// Preview output without side effects
const output = preview(config);
// { meta: [...], jsonLd: {...}, ogImage: {...} }
// List all presets
const presets = listPresets();
// ['ecommerce.productPage', 'blog.articlePage', ...]
`API Reference
$3
React hook that manages document head metadata.
$3
Get requirements for a preset. Returns
{ required, optional, defaults, example }.$3
Validate a config. Returns
{ valid, errors, warnings }.$3
Preview output without side effects. Returns
{ meta, jsonLd, ogImage }.Schema Builders
| Builder | Use Case |
|---------|----------|
|
Product() | E-commerce products |
| Article() | Blog posts, news |
| Organization() | Company info |
| Person() | Author profiles |
| BreadcrumbList() | Navigation breadcrumbs |
| FAQPage() | FAQ sections |
| WebSite()` | Site-wide metadata |- Not just another helmet - Built with AI agents in mind
- Typed structured data - Schema builders with full TypeScript support
- Validation included - Catch SEO mistakes before deploy
- Framework agnostic - Works with any React setup (Vite, CRA, etc.)
MIT