React Native Helmet Async

2.0.4 · active · verified Sun Apr 19

react-native-helmet-async is a specialized fork of `react-helmet-async`, which itself is a modern, thread-safe solution for managing meta tags in React applications. This particular package addresses the specific needs of React Native by removing the `react-dom` peer dependency, making it suitable for environments where DOM rendering is not present. Its core differentiator is the use of a `<HelmetProvider>` component to encapsulate Helmet state on a per-request or per-tree basis, crucial for asynchronous server-side rendering (SSR) to prevent state pollution across requests. It is currently at version 2.0.4 and appears to be actively maintained, providing an essential tool for SEO and head management in React Native web applications (when used with a web renderer) and isomorphic React projects where `react-dom` is not desired. It solves the thread-safety issues inherent in the original `react-helmet`'s `react-side-effect` dependency.

Common errors

```
TypeError: Cannot destructure property 'Helmet' of 'react-native-helmet-async' as it is undefined.
```
cause Attempting to import `Helmet` as a default import when it's a named export.

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

Error: Invariant Violation: Hooks can only be called inside the body of a function component. (e.g., when calling `useContext` outside of a functional component or `Helmet` outside of a provider)

cause Rendering `<Helmet>` or related components without a parent `<HelmetProvider>`.

fix Wrap your application or the specific components using `Helmet` with `<HelmetProvider>`.

```
TypeError: helmet.title is undefined (or similar for meta, link, etc.) in SSR context
```
cause Forgetting to pass a `context` object to `HelmetProvider` during server-side rendering, or not extracting the `helmet` object from that context.

fix Ensure `const helmetContext = {};` is defined and passed as `<HelmetProvider context={helmetContext}>`. After rendering, access properties via `helmetContext.helmet.title.toString()` etc.

Warnings

breaking The default export for `Helmet` was removed in version 1.0.0. You must now use named imports.
Fix: Change `import Helmet from 'react-native-helmet-async';` to `import { Helmet } from 'react-native-helmet-async';`
breaking Introduced the mandatory `HelmetProvider` component to encapsulate Helmet state. All Helmet components must be rendered within a `HelmetProvider`.
Fix: Wrap your root component or the relevant part of your application with `<HelmetProvider>`. For SSR, ensure you pass a `context` prop to the provider.
breaking Server-side rendering no longer uses static `rewind()` or `renderStatic()` methods. State is now extracted via the `context` prop passed to `HelmetProvider`.
Fix: Replace `Helmet.renderStatic()` calls with extracting `helmetContext.helmet` after rendering the app wrapped in `<HelmetProvider context={helmetContext}>`.
gotcha This package is a fork specifically for React Native environments and removes the `react-dom` peer dependency. Using it in a standard web-only React project with `react-dom` might indicate you should be using `react-helmet-async` instead.
Fix: Ensure you understand the specific purpose of this fork. If you need `react-dom`, consider `react-helmet-async`. If you're building for React Native (and a web platform through a renderer), this is appropriate.
gotcha When running Jest tests that emulate SSR, `HelmetProvider.canUseDOM` must be explicitly set to `false` to prevent DOM-dependent behavior.
Fix: Add `HelmetProvider.canUseDOM = false;` in your test setup or before rendering components that use Helmet in a Jest environment.

Install

npm install react-native-helmet-async npm
yarn add react-native-helmet-async yarn
pnpm add react-native-helmet-async pnpm

Imports

Helmet
wrong:
```
import Helmet from 'react-native-helmet-async';
```
correct:
```
import { Helmet } from 'react-native-helmet-async';
```
Since version 1.0.0, Helmet is a named export, not a default export. Ensure you destructure it.
HelmetProvider
wrong:
```
const { HelmetProvider } = require('react-native-helmet-async');
```
correct:
```
import { HelmetProvider } from 'react-native-helmet-async';
```
HelmetProvider is a named export and essential for providing context to Helmet. CommonJS `require` syntax is generally discouraged in modern React/TypeScript projects.
HelmetProvider.canUseDOM
wrong:
```
import { HelmetProvider } from 'react-native-helmet-async'; // Then forget to set canUseDOM
```
correct:
```
HelmetProvider.canUseDOM = false;
```
For Jest tests emulating SSR, you must explicitly set `HelmetProvider.canUseDOM = false;` before rendering to prevent DOM-dependent behavior.

Quickstart

This quickstart demonstrates basic client-side usage of Helmet and HelmetProvider to manage document head tags.

import React from 'react';
import { createRoot } from 'react-dom/client';
import { Helmet, HelmetProvider } from 'react-native-helmet-async';

const App = () => (
  <div>
    <Helmet>
      <title>My Awesome React Native Web App</title>
      <link rel="canonical" href="https://www.example.com/" />
      <meta name="description" content="A test application for react-native-helmet-async" />
    </Helmet>
    <h1>Welcome to the App!</h1>
    <p>Check the document head for the meta tags.</p>
  </div>
);

const container = document.getElementById('root');
if (container) {
  const root = createRoot(container);
  root.render(
    <HelmetProvider>
      <App />
    </HelmetProvider>
  );
} else {
  console.error('Root element not found. Please ensure an element with id "root" exists.');
}

view raw JSON →