Registry / web-framework / react-helmet-async

react-helmet-async

library3.0.0jsnpmunverified

react-helmet-async is a robust solution for managing document head tags (title, meta, link, etc.) in React applications, designed to be thread-safe for server-side rendering (SSR). It addresses the limitations of the original `react-helmet` by encapsulating state on a per-request basis through a `<HelmetProvider>`, crucial for asynchronous SSR environments. The current stable version is 3.0.0, which introduces significant adaptations for React 19+, leveraging React's native metadata hoisting capabilities while maintaining backward compatibility for React 16-18. It differentiates itself by providing a consistent API across React versions, handling `htmlAttributes` and `bodyAttributes` consistently, and offering a context for SSR data extraction, although this context behaves differently in React 19. Releases appear to follow a non-strict cadence, driven by major React version updates and feature enhancements.

web-framework

npm install react-helmet-async

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-HELMET-ASYNC

react-helmet-async

web-frameworkjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Helmet

✓ import { Helmet } from 'react-helmet-async';

✗ import Helmet from 'react-helmet-async';

The default export was removed in version 1.0.0. Named import is required since then.

HelmetProvider

✓ import { HelmetProvider } from 'react-helmet-async';

✗ const { HelmetProvider } = require('react-helmet-async');

Essential for encapsulating Helmet state, especially for SSR. Primarily designed for ESM usage.

HelmetServerState (conceptual)

✓ const { helmet } = helmetContext;

✗ Helmet.renderStatic();

For server-side rendering, state is extracted from the `context` object passed to `HelmetProvider`, replacing the deprecated `renderStatic()` method from prior `react-helmet` versions. In React 19, the context will not be populated for `<title>`, `<meta>`, `<link>` as React handles them natively.

This quickstart demonstrates basic client-side usage of Helmet for managing document head attributes, title, meta, link, style, and script tags within a React application, wrapped in a HelmetProvider.

import React from 'react'; import { createRoot } from 'react-dom/client'; import { Helmet, HelmetProvider } from 'react-helmet-async'; const App = () => ( <div> <Helmet> <html lang="en" amp /> <title>My Awesome App</title> <meta name="description" content="A basic example of react-helmet-async." /> <link rel="canonical" href="https://example.com/" /> <style>{`body { background-color: #f0f0f0; }`}</style> <script type="application/ld+json"> { "@context": "https://schema.org", "@type": "WebSite", "url": "https://example.com/", "name": "My Awesome App" } </script> </Helmet> <h1>Welcome to My Awesome App!</h1> <p>Check the document head for meta tags.</p> </div> ); const rootElement = document.getElementById('app'); if (rootElement) { createRoot(rootElement).render( <HelmetProvider> <App /> </HelmetProvider> ); } else { console.error('Root element #app not found!'); }

Debug

Known issues

breakingStarting with version 1.0.0, the package no longer provides a default export. Attempting to use `import Helmet from 'react-helmet-async'` will result in a runtime error.

fix

Update all imports to use named imports: `import { Helmet, HelmetProvider } from 'react-helmet-async';`

affects: >=1.0.0

breakingFor React 19+, `<HelmetProvider>` becomes a transparent passthrough for `<title>`, `<meta>`, and `<link>` elements, as React 19 handles their hoisting natively. The `context` object for SSR will *not* be populated with these elements when running on React 19. `htmlAttributes` and `bodyAttributes` are still applied via direct DOM manipulation.

fix

If you rely on the SSR `context` object to extract `<title>`, `<meta>`, or `<link>` tags in a React 19 environment, you should instead render these tags directly in your component tree. React 19 will hoist them natively. For `htmlAttributes` and `bodyAttributes`, the context and direct DOM manipulation remain relevant.

affects: >=3.0.0

gotchaUsing `react-helmet-async` without `<HelmetProvider>` will lead to incorrect state management, especially in server-side rendering or concurrent environments, as it relies on the provider to encapsulate state per request. This can cause cross-request data leakage.

fix

Always wrap your React application with `<HelmetProvider>`, both on the client and server. For SSR, ensure you pass a unique `context` object to `<HelmetProvider>` for each request.

affects: >=0.1.0

gotchaThe package is a fork of `react-helmet` specifically to address its thread-safety issues when performing asynchronous operations on the server. If migrating from `react-helmet`, ensure you replace all `Helmet.renderStatic()` calls with the `context` object extraction from `<HelmetProvider>`.

fix

When migrating from `react-helmet`, remove `Helmet.renderStatic()` calls and instead pass a `context` object to `<HelmetProvider>` during SSR. Extract the `helmet` object from this `context` after rendering.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'Helmet' of 'react-helmet-async' as it is undefined.

Attempting to use a default import for Helmet, but it was removed in v1.0.0.

fix

Change `import Helmet from 'react-helmet-async';` to `import { Helmet } from 'react-helmet-async';`

Error: Invariant Violation: Hooks can only be called inside the body of a function component.

This error can occur if `react` is duplicated in your `node_modules` or if `react-helmet-async` is incorrectly linked, causing it to use a different React instance than your application. This often happens with monorepos or mismatched peer dependency resolutions.

fix

Check for duplicate `react` installations using `npm ls react` or `yarn why react`. Use a tool like `resolutions` (Yarn) or `overrides` (NPM 8+) to force a single `react` version. Ensure `react` is correctly specified in `peerDependencies` and installed in your project.

helmetContext.helmet is undefined (during SSR for React 19+)

When running on React 19+, `<title>`, `<meta>`, and `<link>` tags are handled natively by React's head hoisting. The `context` object passed to `HelmetProvider` will therefore not contain these specific tags.

fix

For React 19+, rely on React's native head hoisting for `<title>`, `<meta>`, and `<link>`. If you need to access these tags programmatically on the server, render them directly in your component tree instead of relying solely on `Helmet` and its context extraction.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

reactrequiredCore React dependency for UI component rendering. Required peer dependency.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/staylor/react-helmet-async ↗

packagehttps://www.npmjs.com/package/react-helmet-async ↗