react-helmet-async
Advanced tools
Thread-safe Helmet for React 16–18, with native support for React 19+
Announcement post on Times Open blog
This package is a fork of React Helmet.
<Helmet> usage is synonymous, but server and client now requires <HelmetProvider> to encapsulate state per request.
react-helmet relies on react-side-effect, which is not thread-safe. If you are doing anything asynchronous on the server, you need Helmet to encapsulate data on a per-request basis, this package does just that.
React 19 has built-in support for hoisting <title>, <meta>, <link>, <style>, and <script> elements to <head>. Starting with version 3.0.0, this package detects the React version at runtime:
<Helmet> renders actual DOM elements and lets React handle hoisting them to <head>. <HelmetProvider> becomes a transparent passthrough. The existing API is fully compatible — you do not need to change any code.<Helmet> collects all instances, deduplicates tags, and applies changes to the DOM via manual manipulation (client) or serializes them for the response (server).Note:
htmlAttributesandbodyAttributesdo not have a React 19 equivalent, so they are still applied via direct DOM manipulation on both code paths.
If you are starting a new React 19 project and do not need htmlAttributes/bodyAttributes, SSR context serialization, onChangeClientState, prioritizeSeoTags, or titleTemplate support, you may not need this package at all — React 19's built-in metadata handling may be sufficient.
New in 1.0.0: No more default export! import { Helmet } from 'react-helmet-async'
The main way that this package differs from react-helmet is that it requires using a Provider to encapsulate Helmet state for your React tree. If you use libraries like Redux or Apollo, you are already familiar with this paradigm:
import React from 'react';
import { createRoot } from 'react-dom/client';
import { Helmet, HelmetProvider } from 'react-helmet-async';
const app = (
<HelmetProvider>
<App>
<Helmet>
<title>Hello World</title>
<link rel="canonical" href="https://www.tacobell.com/" />
</Helmet>
<h1>Hello World</h1>
</App>
</HelmetProvider>
);
createRoot(document.getElementById('app')).render(app);
On the server, we will no longer use static methods to extract state. react-side-effect
exposed a .rewind() method, which Helmet used when calling Helmet.renderStatic(). Instead, we are going
to pass a context prop to HelmetProvider, which will hold our state specific to each request.
import React from 'react';
import { renderToString } from 'react-dom/server';
import { Helmet, HelmetProvider } from 'react-helmet-async';
const helmetContext = {};
const app = (
<HelmetProvider context={helmetContext}>
<App>
<Helmet>
<title>Hello World</title>
<link rel="canonical" href="https://www.tacobell.com/" />
</Helmet>
<h1>Hello World</h1>
</App>
</HelmetProvider>
);
const html = renderToString(app);
const { helmet } = helmetContext;
// helmet.title.toString() etc…
React 19 SSR note: When using React 19,
<title>,<meta>, and<link>tags rendered inside<Helmet>are included directly in the React render output and hoisted to<head>by React itself. Thecontextobject will not be populated with helmet state on React 19. If you rely on thecontextfor server rendering, you can render these tags directly in your component tree instead and let React 19 handle them natively.
This package only works with streaming if your <head> data is output outside of renderToNodeStream().
This is possible if your data hydration method already parses your React tree. Example:
import through from 'through';
import { renderToNodeStream } from 'react-dom/server';
import { getDataFromTree } from 'react-apollo';
import { Helmet, HelmetProvider } from 'react-helmet-async';
import template from 'server/template';
const helmetContext = {};
const app = (
<HelmetProvider context={helmetContext}>
<App>
<Helmet>
<title>Hello World</title>
<link rel="canonical" href="https://www.tacobell.com/" />
</Helmet>
<h1>Hello World</h1>
</App>
</HelmetProvider>
);
await getDataFromTree(app);
const [header, footer] = template({
helmet: helmetContext.helmet,
});
res.status(200);
res.write(header);
renderToNodeStream(app)
.pipe(
through(
function write(data) {
this.queue(data);
},
function end() {
this.queue(footer);
this.queue(null);
}
)
)
.pipe(res);
React 19: React 19's
renderToReadableStreamnatively handles<title>,<meta>, and<link>hoisting during streaming, so the manual context extraction shown above is not necessary.
While testing in using jest, if there is a need to emulate SSR, the following string is required to have the test behave the way they are expected to.
import { HelmetProvider } from 'react-helmet-async';
HelmetProvider.canUseDOM = false;
This is only relevant for React 16–18. On React 19,
HelmetProvideris a passthrough andcanUseDOMhas no effect.
It is understood that in some cases for SEO, certain tags should appear earlier in the HEAD. Using the prioritizeSeoTags flag on any <Helmet> component allows the server render of react-helmet-async to expose a method for prioritizing relevant SEO tags.
In the component:
<Helmet prioritizeSeoTags>
<title>A fancy webpage</title>
<link rel="notImportant" href="https://www.chipotle.com" />
<meta name="whatever" value="notImportant" />
<link rel="canonical" href="https://www.tacobell.com" />
<meta property="og:title" content="A very important title"/>
</Helmet>
In your server template:
<html>
<head>
${helmet.title.toString()}
${helmet.priority.toString()}
${helmet.meta.toString()}
${helmet.link.toString()}
${helmet.script.toString()}
</head>
...
</html>
Will result in:
<html>
<head>
<title>A fancy webpage</title>
<meta property="og:title" content="A very important title"/>
<link rel="canonical" href="https://www.tacobell.com" />
<meta name="whatever" value="notImportant" />
<link rel="notImportant" href="https://www.chipotle.com" />
</head>
...
</html>
A list of prioritized tags and attributes can be found in constants.ts.
React 19: The
prioritizeSeoTagsflag has no effect on React 19, since tags are rendered as regular JSX elements and their order in<head>is determined by React's rendering order.
You can optionally use <Helmet> outside a context by manually creating a stateful HelmetData instance, and passing that stateful object to each <Helmet> instance:
import React from 'react';
import { renderToString } from 'react-dom/server';
import { Helmet, HelmetData } from 'react-helmet-async';
const helmetData = new HelmetData({});
const app = (
<App>
<Helmet helmetData={helmetData}>
<title>Hello World</title>
<link rel="canonical" href="https://www.tacobell.com/" />
</Helmet>
<h1>Hello World</h1>
</App>
);
const html = renderToString(app);
const { helmet } = helmetData.context;
React 19: The
helmetDataprop is ignored on React 19, since<Helmet>renders elements directly without the need for external state management.
| React Version | Behavior |
|---|---|
| 16.6+ | Full support via HelmetProvider context and manual DOM updates |
| 17.x | Full support via HelmetProvider context and manual DOM updates |
| 18.x | Full support via HelmetProvider context and manual DOM updates |
| 19.x+ | Renders native JSX elements; React handles <head> hoisting |
pnpm install
pnpm test # unit tests
pnpm run test:e2e # server + browser e2e tests
pnpm run test:all # everything
Licensed under the Apache 2.0 License, Copyright © 2018 Scott Taylor
This is the predecessor of react-helmet-async. It offers similar functionality for managing the document head, but it is not thread-safe and can have issues with server-side rendering in concurrent mode.
A plugin for Next.js projects that provides a set of SEO components and helpers. It is similar to react-helmet-async but is specifically tailored for Next.js and includes additional SEO features.
A lightweight package for managing HTML meta tags in React applications. It is similar to react-helmet-async but with a simpler API and less overhead.
FAQs
Thread-safe Helmet for React 16–18, with native support for React 19+
The npm package react-helmet-async receives a total of 3,822,801 weekly downloads. As such, react-helmet-async popularity was classified as popular.
We found that react-helmet-async demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Socket won two 2026 Reppy Awards from RepVue, ranking in the top 5% of all sales orgs. AE Alexandra Lister shares what it's like to grow a sales career here.
Security News
NIST will stop enriching most CVEs under a new risk-based model, narrowing the NVD's scope as vulnerability submissions continue to surge.
Company News
/Security News
Socket is an initial recipient of OpenAI's Cybersecurity Grant Program, which commits $10M in API credits to defenders securing open source software.