or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdserver-side-rendering.md
tile.json

tessl/npm-react-helmet

A document head manager for React applications enabling dynamic control of HTML head elements

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-helmet@6.1.x

To install, run

npx @tessl/cli install tessl/npm-react-helmet@6.1.0

index.mddocs/

React Helmet

React Helmet is a document head manager for React applications that allows dynamic control of HTML head elements including title, meta tags, links, scripts, and other head content. It provides a declarative API through a Helmet component with nested component override capabilities and full server-side rendering support.

Package Information

  • Package Name: react-helmet
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install react-helmet
  • Peer Dependencies: React >=16.3.0

Core Imports

import { Helmet } from "react-helmet";

For default import:

import Helmet from "react-helmet";

CommonJS:

const { Helmet } = require("react-helmet");

Basic Usage

import React from "react";
import { Helmet } from "react-helmet";

function MyApp() {
  return (
    <div className="application">
      <Helmet>
        <meta charSet="utf-8" />
        <title>My Page Title</title>
        <meta name="description" content="My page description" />
        <link rel="canonical" href="https://mysite.com/example" />
      </Helmet>
      
      <h1>Page Content</h1>
    </div>
  );
}

Architecture

React Helmet is built around several key components:

  • Declarative API: Use standard HTML tags as children to manage head elements
  • Component Nesting: Deeper nested components override parent head changes
  • Side Effect Management: Uses react-side-effect to synchronize component state with DOM
  • Server Rendering: Static methods extract head data for server-side rendering
  • Deduplication: Automatically handles duplicate head elements with priority rules

Capabilities

Document Head Management

Core functionality for managing HTML head elements through declarative React components. Supports all valid head tags with automatic deduplication and nested component override behavior.

function Helmet(props: HelmetProps): JSX.Element;

interface HelmetProps {
  /** Document title */
  title?: string;
  /** Fallback title when titleTemplate exists but no title is defined */
  defaultTitle?: string;
  /** Template for title with %s placeholder */
  titleTemplate?: string;
  /** Attributes for the title element */
  titleAttributes?: object;
  /** Attributes for the html element */
  htmlAttributes?: object;
  /** Attributes for the body element */
  bodyAttributes?: object;
  /** Array of meta tag objects */
  meta?: Array<object>;
  /** Array of link tag objects */
  link?: Array<object>;
  /** Array of script tag objects */
  script?: Array<object>;
  /** Array of style tag objects */
  style?: Array<object>;
  /** Array of noscript tag objects */
  noscript?: Array<object>;
  /** Base tag configuration */
  base?: object;
  /** Controls whether to use requestAnimationFrame for DOM updates (default: true) */
  defer?: boolean;
  /** Controls HTML entity encoding (server-side only) (default: true) */
  encodeSpecialCharacters?: boolean;
  /** Callback function that tracks DOM changes */
  onChangeClientState?: (newState: any, addedTags: any[], removedTags: any[]) => void;
  /** Child elements representing head tags */
  children?: React.ReactNode;
}

Server-Side Rendering

Extract head data after server-side rendering for inclusion in HTML documents. Essential for SEO and prerendering scenarios.

/** Extract head data after server-side rendering - must be called on server */
static renderStatic(): HelmetData;

/** Legacy alias for renderStatic() */
static rewind(): HelmetData;

/** Testing utility to get current state without resetting instance stack */
static peek(): HelmetData;

/** Controls DOM usage detection for server environments */
static set canUseDOM(value: boolean);

interface HelmetData {
  title: HelmetElement;
  base: HelmetElement;
  meta: HelmetElement;
  link: HelmetElement;
  script: HelmetElement;
  style: HelmetElement;
  noscript: HelmetElement;
  htmlAttributes: HelmetElement;
  bodyAttributes: HelmetElement;
}

interface HelmetElement {
  /** Convert to React components for JSX rendering */
  toComponent(): React.ReactElement[];
  /** Convert to HTML string for server-side rendering */
  toString(): string;
}

Server-Side Rendering

Supported Head Elements

React Helmet supports all valid HTML head elements:

Title Management

// Simple title
<title>Page Title</title>

// Title with attributes
<title itemProp="name" lang="en">Attributed Title</title>

// Title templating
<Helmet titleTemplate="MySite.com - %s">
  <title>Page Name</title>
</Helmet>
// Results in: "Page Name - MySite.com"

Meta Tags

<meta name="description" content="Page description" />
<meta property="og:type" content="article" />
<meta charSet="utf-8" />
<meta httpEquiv="X-UA-Compatible" content="IE=edge" />

Link Elements

<link rel="canonical" href="https://example.com/page" />
<link rel="stylesheet" href="/styles.css" />
<link rel="apple-touch-icon" sizes="180x180" href="/icon.png" />

Script Elements

// External scripts
<script src="https://example.com/script.js" type="text/javascript" />

// Inline scripts
<script type="application/ld+json">{`
  {
    "@context": "https://schema.org",
    "@type": "WebPage"
  }
`}</script>

Style Elements

<style type="text/css">{`
  body { background-color: blue; }
  .main { font-size: 16px; }
`}</style>

Other Elements

// Base element
<base target="_blank" href="https://example.com/" />

// Noscript fallbacks
<noscript>{`
  <link rel="stylesheet" type="text/css" href="fallback.css" />
`}</noscript>

// HTML and body attributes
<html lang="en" dir="ltr" />
<body className="app-root" data-theme="dark" />

Component Behavior

Nested Override Pattern

Deeper components override parent head changes, allowing flexible head management in component hierarchies:

<App>
  <Helmet>
    <title>App Title</title>
    <meta name="description" content="App description" />
  </Helmet>
  
  <ProductPage>
    <Helmet>
      <title>Product Page</title>
      <meta name="description" content="Product description" />
    </Helmet>
  </ProductPage>
</App>

// Result: title="Product Page", description="Product description"

Duplicate Handling

Multiple instances of the same tag type are preserved when specified in the same component, but deduplicated across components:

// Same component - both icons preserved
<Helmet>
  <link rel="apple-touch-icon" sizes="57x57" href="/icon-57.png" />
  <link rel="apple-touch-icon" sizes="72x72" href="/icon-72.png" />
</Helmet>

// Different components - deeper component wins
<Parent>
  <Helmet>
    <link rel="canonical" href="https://example.com/parent" />
  </Helmet>
  <Child>
    <Helmet>
      <link rel="canonical" href="https://example.com/child" />
    </Helmet>
  </Child>
</Parent>
// Result: canonical = "https://example.com/child"