# react-head-safe
[](https://www.npmjs.com/package/react-head-safe)
[](https://www.npmjs.com/package/react-head-safe)
[](https://codecov.io/gh/umsungjun/react-head-safe)
[English](README.md) | [한국어](README.ko.md)
**A lightweight React head manager for client-side rendering (CSR) applications.**
Safely manage document title, meta tags, Open Graph tags, and SEO metadata without duplicates. Perfect for React SPAs, Vite, and Create React App projects.
## Important: SEO in CSR Applications
Since CSR apps run JavaScript on the client side, search engine crawlers and social media bots may not execute your JavaScript. This means **dynamically injected meta tags might not be recognized**.
For optimal SEO, always set default meta tags directly in your `index.html`:
```html
My App
```
`react-head-safe` will **override these defaults at runtime** when JavaScript executes, allowing page-specific meta tags for each route. This two-layer approach ensures:
1. **Crawlers without JS execution** see meaningful default meta tags from `index.html`
2. **Crawlers with JS execution** (e.g., Googlebot) and **users** see page-specific meta tags set by `react-head-safe`
## Why react-head-safe?
A lightweight, CSR-focused alternative for managing document head elements in React. Perfect for simple client-side rendered applications that need:
- **Explicit duplicate prevention** - Always removes existing meta tags before adding new ones
- **Simplicity** - Just a single component with props, no complex setup
- **Performance** - Uses `useLayoutEffect` for synchronous DOM updates before paint
- **Type safety** - Written in TypeScript with full type definitions
## Features
- ✅ **No Duplicate Tags** - Removes existing meta tags before creating new ones
- ✅ **TypeScript Support** - Full type safety with TypeScript
- ✅ **Lightweight** - Zero dependencies except React
- ✅ **CSR Optimized** - Uses `useLayoutEffect` for synchronous DOM updates
- ✅ **Open Graph Support** - Built-in support for social media meta tags
- ✅ **Twitter Card Support** - Automatically sets Twitter tags when Open Graph tags are provided
- ✅ **Simple API** - Just pass props, no complex configuration
## Installation
Install via npm, yarn, or pnpm:
```bash
npm install react-head-safe
# or
yarn add react-head-safe
# or
pnpm add react-head-safe
```
Zero dependencies required (React is a peer dependency).
## Quick Start
Simply import and use the `ReactHeadSafe` component in your React pages:
```tsx
import { ReactHeadSafe } from 'react-head-safe';
function MyPage() {
return (
<>