or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md core-sanitization.md hooks.md index.md validation-utilities.md

tile.json

Configuration

DOMPurify provides extensive configuration options to control sanitization behavior. The configuration system allows fine-grained control over which elements and attributes are allowed, output formats, security policies, and processing behavior.

Capabilities

Configuration Management

Set and clear global configuration that applies to all subsequent sanitize calls.

/**
 * Set global configuration for all subsequent sanitize calls
 * @param cfg - Configuration object (optional, clears config if not provided)
 */
function setConfig(cfg?: Config): void;

/**
 * Clear the current configuration, reverting to defaults
 */
function clearConfig(): void;

Usage Examples:

import DOMPurify from "dompurify";

// Set global configuration
DOMPurify.setConfig({
  ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p', 'br'],
  ALLOWED_ATTR: ['href', 'title'],
  ALLOW_DATA_ATTR: false
});

// All subsequent calls use this configuration
const clean1 = DOMPurify.sanitize(dirtyHTML1);
const clean2 = DOMPurify.sanitize(dirtyHTML2);

// Clear configuration back to defaults
DOMPurify.clearConfig();

// Per-call configuration (doesn't affect global config)
const clean3 = DOMPurify.sanitize(dirtyHTML3, {
  ALLOWED_TAGS: ['span', 'div'],
  FORBID_ATTR: ['style']
});

Tag and Attribute Control

Control which HTML tags and attributes are allowed or forbidden during sanitization.

interface TagAttributeConfig {
  /**
   * Array of allowed HTML tag names (overrides defaults)
   */
  ALLOWED_TAGS?: string[];
  
  /**
   * Array of allowed attribute names (overrides defaults)
   */
  ALLOWED_ATTR?: string[];
  
  /**
   * Add tags to the default allowed list
   */
  ADD_TAGS?: string[];
  
  /**
   * Add attributes to the default allowed list
   */
  ADD_ATTR?: string[];
  
  /**
   * Array of forbidden tag names (overrides allowed tags)
   */
  FORBID_TAGS?: string[];
  
  /**
   * Array of forbidden attribute names (overrides allowed attributes)
   */
  FORBID_ATTR?: string[];
  
  /**
   * Elements whose content should be removed when the element is removed
   */
  FORBID_CONTENTS?: string[];
}

Usage Examples:

// Allow only specific tags and attributes
DOMPurify.sanitize(html, {
  ALLOWED_TAGS: ['p', 'br', 'strong', 'em'],
  ALLOWED_ATTR: ['class', 'id']
});

// Add to default allowed lists
DOMPurify.sanitize(html, {
  ADD_TAGS: ['custom-element'],
  ADD_ATTR: ['data-custom']
});

// Forbid specific elements (even if normally allowed)
DOMPurify.sanitize(html, {
  FORBID_TAGS: ['img', 'video'],
  FORBID_ATTR: ['onclick', 'onerror']
});

// Remove content when removing parent element
DOMPurify.sanitize(html, {
  FORBID_CONTENTS: ['script', 'style']
});

Namespace and Protocol Control

Configure allowed XML namespaces, URI protocols, and namespace-specific behavior.

interface NamespaceProtocolConfig {
  /**
   * Array of allowed XML namespaces for elements
   */
  ALLOWED_NAMESPACES?: string[];
  
  /**
   * Allow unknown protocols in URL attributes (default: false)
   */
  ALLOW_UNKNOWN_PROTOCOLS?: boolean;
  
  /**
   * Custom regex for allowed URI protocols
   */
  ALLOWED_URI_REGEXP?: RegExp;
  
  /**
   * Add attributes that are safe for URI-like values
   */
  ADD_URI_SAFE_ATTR?: string[];
  
  /**
   * Add tags that can safely use data: URIs
   */
  ADD_DATA_URI_TAGS?: string[];
  
  /**
   * Change the default namespace (default: HTML)
   */
  NAMESPACE?: string;
  
  /**
   * Map of HTML elements that allow MathML/SVG content
   */
  HTML_INTEGRATION_POINTS?: Record<string, boolean>;
  
  /**
   * Map of MathML elements that allow HTML content
   */
  MATHML_TEXT_INTEGRATION_POINTS?: Record<string, boolean>;
  
  /**
   * Parser media type for XML vs HTML processing
   */
  PARSER_MEDIA_TYPE?: 'text/html' | 'application/xhtml+xml';
}

Usage Examples:

// Custom URI protocol handling
DOMPurify.sanitize(html, {
  ALLOW_UNKNOWN_PROTOCOLS: true,
  ALLOWED_URI_REGEXP: /^(?:https?|ftp|mailto|tel|custom-protocol):/i
});

// SVG and MathML namespace support
DOMPurify.sanitize(svgContent, {
  ALLOWED_NAMESPACES: [
    'http://www.w3.org/1999/xhtml',
    'http://www.w3.org/2000/svg',
    'http://www.w3.org/1998/Math/MathML'
  ]
});

// XHTML processing
DOMPurify.sanitize(xhtmlContent, {
  PARSER_MEDIA_TYPE: 'application/xhtml+xml',
  NAMESPACE: 'http://www.w3.org/1999/xhtml'
});

Attribute Behavior Control

Control how different types of attributes are handled during sanitization.

interface AttributeBehaviorConfig {
  /**
   * Allow ARIA attributes (default: true)
   */
  ALLOW_ARIA_ATTR?: boolean;
  
  /**
   * Allow HTML5 data-* attributes (default: true)
   */
  ALLOW_DATA_ATTR?: boolean;
  
  /**
   * Allow self-closing tags in attributes (default: true)
   */
  ALLOW_SELF_CLOSE_IN_ATTR?: boolean;
}

Usage Examples:

// Strict attribute filtering
DOMPurify.sanitize(html, {
  ALLOW_ARIA_ATTR: false,    // Remove aria-* attributes
  ALLOW_DATA_ATTR: false,    // Remove data-* attributes
  ALLOW_SELF_CLOSE_IN_ATTR: false  // Remove self-closing tags in attributes
});

// Accessibility-friendly configuration
DOMPurify.sanitize(html, {
  ALLOW_ARIA_ATTR: true,     // Keep ARIA attributes for screen readers
  ADD_ATTR: ['role', 'tabindex', 'alt']
});

Output Format Configuration

Control the format and type of sanitized output returned by DOMPurify.

interface OutputFormatConfig {
  /**
   * Return DOM node instead of HTML string (default: false)
   */
  RETURN_DOM?: boolean;
  
  /**
   * Return DocumentFragment instead of HTML string (default: false)
   */
  RETURN_DOM_FRAGMENT?: boolean;
  
  /**
   * Return TrustedHTML object when supported (default: false)
   */
  RETURN_TRUSTED_TYPE?: boolean;
  
  /**
   * Return entire document including <html> tags (default: false)
   */
  WHOLE_DOCUMENT?: boolean;
  
  /**
   * Sanitize node in-place rather than creating copy (default: false)
   */
  IN_PLACE?: boolean;
}

Usage Examples:

// Get DOM node for direct manipulation
const cleanNode = DOMPurify.sanitize(html, { 
  RETURN_DOM: true 
}) as HTMLElement;
document.body.appendChild(cleanNode);

// Get DocumentFragment for multiple elements
const fragment = DOMPurify.sanitize(html, { 
  RETURN_DOM_FRAGMENT: true 
});
container.appendChild(fragment);

// Complete HTML document
const fullDoc = DOMPurify.sanitize(htmlDoc, { 
  WHOLE_DOCUMENT: true 
});

// TrustedHTML for CSP compatibility
const trustedHTML = DOMPurify.sanitize(html, { 
  RETURN_TRUSTED_TYPE: true 
});
element.innerHTML = trustedHTML;

Security and Safety Options

Configure security-related behaviors and safety measures.

interface SecurityConfig {
  /**
   * Make output safe for template engines (default: false)
   */
  SAFE_FOR_TEMPLATES?: boolean;
  
  /**
   * Handle XML content safely (default: true)
   */
  SAFE_FOR_XML?: boolean;
  
  /**
   * Use DOM Clobbering protection (default: true)
   */
  SANITIZE_DOM?: boolean;
  
  /**
   * Isolate named properties with prefix (default: false)
   */
  SANITIZE_NAMED_PROPS?: boolean;
  
  /**
   * Custom prefix for named properties when SANITIZE_NAMED_PROPS is true (default: "user-content-")
   */
  SANITIZE_NAMED_PROPS_PREFIX?: string;
  
  /**
   * Keep element content when removing elements (default: true)
   */
  KEEP_CONTENT?: boolean;
  
  /**
   * Force elements into document.body (default: false)
   */
  FORCE_BODY?: boolean;
}

Usage Examples:

// Template-safe output (removes template expressions)
DOMPurify.sanitize(html, {
  SAFE_FOR_TEMPLATES: true  // Removes {{ }}, <% %>, ${ } expressions
});

// Maximum DOM clobbering protection
DOMPurify.sanitize(html, {
  SANITIZE_DOM: true,
  SANITIZE_NAMED_PROPS: true  // Prefixes id/name with "user-content-"
});

// Preserve text content when removing dangerous elements
DOMPurify.sanitize('<script>alert("xss")</script>Hello', {
  KEEP_CONTENT: true  // Keeps "Hello" text
});

Profile-Based Configuration

Use predefined configurations for common use cases.

interface ProfileConfig {
  /**
   * Use predefined tag/attribute profiles
   */
  USE_PROFILES?: {
    html?: boolean;      // Allow safe HTML elements
    svg?: boolean;       // Allow safe SVG elements  
    svgFilters?: boolean; // Allow SVG filter elements
    mathMl?: boolean;    // Allow safe MathML elements
  } | false;
}

Usage Examples:

// HTML-only content
DOMPurify.sanitize(content, {
  USE_PROFILES: { html: true }
});

// SVG graphics with HTML
DOMPurify.sanitize(content, {
  USE_PROFILES: { 
    html: true,
    svg: true 
  }
});

// Mathematical content
DOMPurify.sanitize(content, {
  USE_PROFILES: { 
    html: true,
    mathMl: true 
  }
});

// Rich content with all safe elements
DOMPurify.sanitize(content, {
  USE_PROFILES: { 
    html: true,
    svg: true,
    svgFilters: true,
    mathMl: true 
  }
});

Custom Element Handling

Configure how custom elements and their attributes are processed.

interface CustomElementConfig {
  /**
   * Custom element handling configuration
   */
  CUSTOM_ELEMENT_HANDLING?: {
    /**
     * Function or regex to validate custom element tag names
     */
    tagNameCheck?: RegExp | ((tagName: string) => boolean) | null;
    
    /**
     * Function or regex to validate custom element attribute names  
     */
    attributeNameCheck?: RegExp | ((attributeName: string) => boolean) | null;
    
    /**
     * Allow customized built-in elements (default: false)
     */
    allowCustomizedBuiltInElements?: boolean;
  };
}

Usage Examples:

// Allow specific custom elements
DOMPurify.sanitize(html, {
  CUSTOM_ELEMENT_HANDLING: {
    tagNameCheck: /^my-/,  // Allow tags starting with "my-"
    attributeNameCheck: /^data-my-/,  // Allow attributes starting with "data-my-"
    allowCustomizedBuiltInElements: true
  }
});

// Function-based validation
DOMPurify.sanitize(html, {
  CUSTOM_ELEMENT_HANDLING: {
    tagNameCheck: (tagName) => {
      return ['allowed-component', 'safe-widget'].includes(tagName);
    },
    attributeNameCheck: (attrName) => {
      return attrName.startsWith('safe-') || attrName === 'data-config';
    }
  }
});

Trusted Types Integration

Configure Trusted Types policy for CSP-compliant applications.

interface TrustedTypesConfig {
  /**
   * Custom Trusted Types policy (must implement createHTML and createScriptURL)
   */
  TRUSTED_TYPES_POLICY?: TrustedTypePolicy;
}

Usage Examples:

// Custom Trusted Types policy
const customPolicy = trustedTypes.createPolicy('my-sanitizer', {
  createHTML: (input) => DOMPurify.sanitize(input),
  createScriptURL: (input) => input  // Custom logic here
});

DOMPurify.sanitize(html, {
  TRUSTED_TYPES_POLICY: customPolicy,
  RETURN_TRUSTED_TYPE: true
});

Version

Tile

Files

configuration.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Configuration

Capabilities

Configuration Management

Tag and Attribute Control

Namespace and Protocol Control

Attribute Behavior Control

Output Format Configuration

Security and Safety Options

Profile-Based Configuration

Custom Element Handling

Trusted Types Integration

configuration.mddocs/