react-safe-html-parser/dist/index.d.ts

A secure, lightweight HTML parser for React with XSS protection and SSR support

import React$1, { ComponentType, ReactNode, ReactElement, CSSProperties } from 'react';

interface ParserOptions {
    /** Allow custom component replacements for HTML tags */
    components?: ComponentMap;
    /** Custom transform function to modify nodes during parsing */
    transform?: TransformFunction;
    /** Sanitization settings */
    sanitize?: SanitizeOptions;
    /** Whether to decode HTML entities */
    decodeHtmlEntities?: boolean;
    /** Whether to convert style strings to objects */
    parseStyle?: boolean;
    /** Custom HTML entity decoder */
    entityDecoder?: (entity: string) => string;
}
interface ComponentMap {
    [tagName: string]: ComponentType<any>;
}
interface TransformFunction {
    (node: ParsedNode, index: number, parent?: ParsedNode): ReactNode | null;
}
interface SanitizeOptions {
    /** Allowed HTML tags */
    allowedTags?: string[];
    /** Allowed HTML attributes */
    allowedAttributes?: string[];
    /** Allowed CSS properties */
    allowedStyles?: string[];
    /** Whether to remove all script tags and event handlers */
    removeScripts?: boolean;
    /** Whether to remove all style tags */
    removeStyles?: boolean;
    /** Whether to remove all comments */
    removeComments?: boolean;
}
interface ParsedNode {
    type: 'element' | 'text' | 'comment';
    tagName?: string;
    attributes?: Record<string, string>;
    children?: ParsedNode[];
    text?: string;
    nodeType: number;
}
interface HtmlParserProps {
    /** HTML string to parse */
    html: string;
    /** Parser options */
    options?: ParserOptions;
    /** CSS class name for the wrapper element */
    className?: string;
    /** CSS styles for the wrapper element */
    style?: CSSProperties;
    /** Fallback content when parsing fails */
    fallback?: ReactNode;
    /** Whether to show parsing errors */
    showErrors?: boolean;
}
interface ParseResult {
    /** Parsed React elements */
    elements: ReactElement[];
    /** Any parsing errors */
    errors: Error[];
    /** Whether parsing was successful */
    success: boolean;
}
interface IsomorphicDOMParser {
    parseHTML: (html: string) => {
        document: Document;
        window: Window;
    };
}
interface SecurityConfig {
    /** Dangerous attributes to remove */
    dangerousAttributes: string[];
    /** Dangerous protocols to remove */
    dangerousProtocols: string[];
    /** Dangerous tags to remove */
    dangerousTags: string[];
    /** Allowed attributes by tag */
    allowedAttributesByTag: Record<string, string[]>;
}

/**
 * PURE FUNCTION: Parse HTML string into React elements (array)
 * Safe for SSR, PDF, and all React renderers. No hooks, no context required.
 */
declare function parseHtmlToReact(html: string, options?: ParserOptions): ParseResult;
/**
 * PURE FUNCTION: Parse HTML string and return a single React element (wrapped in Fragment if multiple)
 * Safe for SSR, PDF, and all React renderers. No hooks, no context required.
 */
declare function parseHtmlToElement(html: string, options?: ParserOptions): React$1.ReactElement | null;

/**
 * React DOM only: Uses hooks for memoization. NOT for SSR/PDF.
 */
declare const HtmlParser: React$1.FC<HtmlParserProps>;
/**
 * Suspense-wrapped version for dynamic parsing (React DOM only)
 */
declare const AsyncHtmlParser: React$1.FC<HtmlParserProps>;

/**
 * Static HTML parser component that doesn't use any React hooks
 * Safe for SSR, PDF rendering, and other contexts where hooks aren't available
 */
declare const HtmlParserStatic: React$1.FC<HtmlParserProps>;

/**
 * SSR-safe HTML parser that doesn't use any hooks
 * This component is completely safe for server-side rendering
 */
declare const SSRHtmlParser: React$1.FC<{
    html: string;
    options?: ParserOptions;
    className?: string;
    style?: React$1.CSSProperties;
    fallback?: React$1.ReactNode;
    showErrors?: boolean;
}>;

/**
 * Creates an isomorphic DOM parser that works in both browser and Node.js environments
 */
declare function createIsomorphicDOMParser(): IsomorphicDOMParser;
/**
 * Default isomorphic DOM parser instance
 */
declare const isomorphicDOMParser: IsomorphicDOMParser;
/**
 * Safely parse HTML string into a DOM document
 */
declare function parseHTML(html: string): Document;

/**
 * Pure utility function to parse HTML without any React components
 * Safe for SSR and any environment where React isn't available
 */
declare function parseHtmlToReactElement(html: string, options?: ParserOptions): React.ReactElement | null;
/**
 * Parse HTML and return React elements array
 * Safe for SSR and any environment where React isn't available
 */
declare function parseHtmlToReactElements(html: string, options?: ParserOptions): React.ReactElement[];

/**
 * Default security configuration
 */
declare const DEFAULT_SECURITY_CONFIG: SecurityConfig;
/**
 * Check if a URL is dangerous
 */
declare function isDangerousUrl(url: string): boolean;
/**
 * Check if an attribute is dangerous
 */
declare function isDangerousAttribute(attr: string): boolean;
/**
 * Check if a tag is dangerous
 */
declare function isDangerousTag(tag: string): boolean;
/**
 * Sanitize HTML attributes
 */
declare function sanitizeAttributes(attributes: Record<string, string>, tagName: string, options?: SanitizeOptions): Record<string, string>;
/**
 * Sanitize CSS styles
 */
declare function sanitizeStyles(styleString: string, options?: SanitizeOptions): Record<string, string>;
/**
 * Decode HTML entities
 */
declare function decodeHtmlEntities(text: string): string;

export { AsyncHtmlParser, DEFAULT_SECURITY_CONFIG, HtmlParser, HtmlParserStatic, SSRHtmlParser, createIsomorphicDOMParser, decodeHtmlEntities, HtmlParser as default, isDangerousAttribute, isDangerousTag, isDangerousUrl, isomorphicDOMParser, parseHTML, parseHtmlToElement, parseHtmlToReact, parseHtmlToReactElement, parseHtmlToReactElements, sanitizeAttributes, sanitizeStyles };
export type { ComponentMap, HtmlParserProps, IsomorphicDOMParser, ParseResult, ParsedNode, ParserOptions, SanitizeOptions, SecurityConfig, TransformFunction };