safe-html-react-parser

A secure wrapper for html-react-parser with DOMPurify that automatically sanitizes HTML before parsing.

What it does

- 🛡️ Security: Automatically sanitizes malicious HTML using DOMPurify
- ⚛️ React: Seamlessly integrates with html-react-parser
- 🌐 Universal: Works in both browser and Node.js (SSR) environments
- 🏷️ Custom Tags: Handles project-specific tags like safely
- 🚀 Flexible: Choose your DOM implementation (jsdom, happy-dom, or linkedom)
- ⚡ Optimized: Built-in caching and memory management

Installation

``bash
npm install @naverpay/safe-html-react-parser
`

$3

For server-side rendering, you need to install one of the following DOM implementations:

`bash


Option 1: jsdom (most complete, heavier)

`tsx
import { safeParse } from '@naverpay/safe-html-react-parser'

// Basic usage - automatically sanitizes dangerous HTML
const Component = () => {
const maliciousHtml = '

Hello World

- htmlString (string): The HTML string to parse
- options (SafeParseOptions, optional): Configuration options

#### Options

`typescript
interface SafeParseOptions extends HTMLReactParserOptions {
// DOMPurify configuration
sanitizeConfig?: DOMPurify.Config

// Custom tags to preserve during sanitization
preserveCustomTags?: string[]
}
`

#### Returns

React elements or array of React elements

Advanced Usage

$3

`tsx
import { safeParse } from '@naverpay/safe-html-react-parser'

const html = '

const result = safeParse(html, {
sanitizeConfig: {
ALLOWED_TAGS: ['div', 'p', 'style'], // Allow style tags
ALLOWED_ATTR: ['class'],
ALLOW_ARIA_ATTR: true
}
})
`

$3

Use preserveCustomTags to preserve project-specific tags that would otherwise be removed:

`tsx
import { safeParse } from '@naverpay/safe-html-react-parser'

// Preserve custom tags like , , etc.
const svgContent = ''

const result = safeParse(svgContent, {
preserveCustomTags: ['g', 'path'],
replace: (domNode) => {
if (domNode.name === 'g') {
return {/ custom rendering /}
}
if (domNode.name === 'path') {
return
}
}
})
`

$3

All html-react-parser options are supported:

`tsx
import { safeParse } from '@naverpay/safe-html-react-parser'

const html = '

Hello

const result = safeParse(html, {
replace: (domNode) => {
if (domNode.name === 'img') {
return
}
},
trim: true
})
`

$3

You have two ways to configure the DOM implementation:

#### Method 1: Per-call configuration (Recommended)

Pass domPurifyOptions directly to safeParse():

`tsx
import { safeParse } from '@naverpay/safe-html-react-parser'
import { Window } from 'happy-dom'

const result = safeParse(htmlString, {
domPurifyOptions: {
domWindowFactory: () => new Window(),
enableCache: true,
maxCacheSize: 100
}
})
`

#### Method 2: Global configuration

Configure once at app initialization:

`tsx
import { configureDOMPurify } from '@naverpay/safe-html-react-parser'

// Using jsdom
import { JSDOM } from 'jsdom'
configureDOMPurify({
domWindowFactory: () => new JSDOM(''),
enableCache: true,
maxCacheSize: 100,
recreateInterval: 1000 // Recreate DOM instance every 1000 sanitizations
})

// Using happy-dom (recommended for better performance)
import { Window } from 'happy-dom'
configureDOMPurify({
domWindowFactory: () => new Window(),
enableCache: true,
recreateInterval: 500
})

// Using linkedom (fastest, minimal footprint)
import { parseHTML } from 'linkedom'
configureDOMPurify({
domWindowFactory: () => parseHTML(''),
enableCache: true
})
`

> [!NOTE]
>
> If you don't configure anything, the library will automatically try jsdom → happy-dom → linkedom in that order.

Default Allowed Tags

By default, the following HTML tags are allowed:

`typescript
ALLOWED_TAGS: [
'p', 'br', 'strong', 'em', 'b', 'i', 'u', 'span', 'div',
'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'h',
'ul', 'ol', 'li', 'dl', 'dt', 'dd',
'a', 'img'
]
`

Performance Optimization

$3

By default, caching is enabled to improve performance:

`tsx
configureDOMPurify({
enableCache: true, // Default: true
maxCacheSize: 100, // Default: 100
})
`

$3

The DOM instance is automatically recreated periodically to prevent memory leaks:

`tsx
configureDOMPurify({
recreateInterval: 1000 // Default: 1000 sanitization calls
})
`

$3

| Implementation | Speed | Memory | Completeness | Recommended For |
|----------------|-------|--------|--------------|-----------------|
| jsdom | Slower | Higher | Most complete | Maximum compatibility |
| happy-dom | Fast | Medium | Good | Balanced (Recommended) |
| linkedom | Fastest | Lowest | Basic | Performance-critical apps |

Security Notes

- All HTML is sanitized by DOMPurify before parsing
- Dangerous tags like