A modern head manager for React, inspired by react-helmet with additional features and async support.
npm install react-helmet-pro, , , , structured data, favicons, analytics, and security headers designed for real world production use.
, , , injection
collectHelmetTags()
bash
or with npm
npm install react-helmet-pro
with pnpm
pnpm add react-helmet-pro
or with yarn
yarn add react-helmet-pro
`
---
Basic Usage
$3
`tsx
import { HelmetProvider } from 'react-helmet-pro';
function App() {
return (
);
}
`
$3
`tsx
import { Helmet } from 'react-helmet-pro';
title="About Us"
meta={[
{ name: 'description', content: 'Learn about our company' },
{ name: 'keywords', content: 'company, team, about' },
]}
/>
`
$3
`tsx
import { StructuredData } from 'react-helmet-pro';
json={{
'@context': 'https://schema.org',
'@type': 'Organization',
name: 'React Helmet Pro Inc.',
url: 'https://reacthelmetpro.dev',
}}
/>
`
$3
`tsx
import { Analytics } from 'react-helmet-pro';
`
---
Middleware Example
You can define reusable middleware functions to extend or modify head data.
`ts
// middleware/withSiteSuffix.ts
export const withSiteSuffix = (head) => {
if (head.title) {
return { ...head, title: ${head.title} | My Awesome Site };
}
return head;
};
`
Apply it in your component:
`tsx
import { useHelmetMiddleware } from 'react-helmet-pro';
import { withSiteSuffix } from './middleware/withSiteSuffix';
useHelmetMiddleware(withSiteSuffix);
`
---
Next.js Usage
react-helmet-pro works seamlessly with Next.js, including full support for Server Side Rendering (SSR) and App Router. Follow these steps to integrate it:
$3
Wrap your app in the HelmetProvider:
`tsx
// app/layout.tsx (App Router)
import './globals.css';
import { HelmetProvider } from 'react-helmet-pro';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
`
> 💡 Note: HelmetProvider must be used inside the tag, not the in App Router.
---
$3
`tsx
// app/about/page.tsx or any client component
'use client';
import { Helmet } from 'react-helmet-pro';
export default function AboutPage() {
return (
<>
title="About Us"
meta={[
{ name: 'description', content: 'Learn about our company' },
{ name: 'keywords', content: 'company, team, about' },
]}
/>
About Us
>
);
}
`
---
$3
If you are using custom SSR setup with getServerSideProps or want finer control, you can extract head tags server-side:
`tsx
// In custom _document.tsx for SSR
import Document, { Html, Head, Main, NextScript } from 'next/document';
import { collectHelmetTags } from 'react-helmet-pro';
class MyDocument extends Document {
static async getInitialProps(ctx) {
const initialProps = await Document.getInitialProps(ctx);
const helmetTags = collectHelmetTags(/ your Helmet elements /);
return {
...initialProps,
helmetTags,
};
}
render() {
// Inject head tags here if extracted manually
return (
{/ SSR extracted tags can go here if needed /}
);
}
}
export default MyDocument;
`
---
$3
`tsx
// client/components/HeadWrapper.tsx
'use client';
import { useHelmetMiddleware } from 'react-helmet-pro';
import { withSiteSuffix } from '../middleware/withSiteSuffix';
export default function HeadWrapper() {
useHelmetMiddleware(withSiteSuffix);
return null;
}
`
Use HelmetWrapper at the top of your page/component to apply middleware.
---
$3
- Hydration Mismatch Warning: Avoid using dynamic data like Date.now() or Math.random() in head tags without guards (typeof window !== 'undefined') or snapshotting.
- Always mark Helmet and StructuredData usage in use client components.
---
Components API
$3
| Prop | Type | Description |
|--------|-----------------------------|--------------------------|
| title | string | Sets the page title |
| meta | Array<{ name: string; content: string }> | Injects meta tags |
---
$3
| Prop | Type | Description |
|------|----------|--------------------------|
| json | object | JSON-LD structured data |
---
$3
| Prop | Type | Description |
|------|----------|---------------------|
| href | string | Path to favicon.ico |
---
$3
| Prop | Type | Description |
|------|--------------|---------------------------|
| type | 'gtag' | Currently only supports GTag |
| id | string | Your Google Analytics ID |
---
$3
Injects security-related meta tags like CSP, XSS protection, nosniff headers, etc.
---
SSR Support
$3
`tsx
import { collectHelmetTags } from 'react-helmet-pro';
const headTags = collectHelmetTags(/ JSX head elements /);
// Use this to inject into SSR-rendered HTML
`
---
Testing
Test with Jest + React Testing Library.
`bash
npm run test
`
Example test:
`tsx
render( );
expect(document.title).toBe("Test Page");
`
---
Contributing
We welcome all contributions!
To get started:
`bash
git clone https://github.com/lahiruudayakumara/react-helmet-pro.git
cd react-helmet-pro
pnpm install
pnpm run dev
``