Skip to main content

Getting started

Interweave is a robust React library that can...

  • Safely render HTML without using dangerouslySetInnerHTML.
  • Safely strip HTML tags.
  • Automatic XSS and injection protection.
  • Clean HTML attributes using filters.
  • Interpolate components using matchers.
  • Autolink URLs, IPs, emails, and hashtags.
  • Render Emoji and emoticon characters.
  • And much more!

Requirements​

  • React 16.8+ / 17+
  • IE 11+
  • Emoji support: fetch, sessionStorage

Installation​

yarn add interweave react

Why is it safe?​

Interweave is deemed safe as it doesn't rely on custom HTML parsers (excluding SSR) -- it relies on the browser and DOM itself for parsing. Because of this, we take full control of the parsing flow by inspecting all HTML elements and their attributes, and then filtering problematic values, avoiding vulnerabilities, and closing XSS holes.

We also take this a step further by maintaing an explicit allow, block, and banned list of HTML elements and attributes. Interweave has also been penetration tested multiple times with zero issue!

Usage​

Interweave can primarily be used with the <Interweave /> and <Markup /> components, both of which provide an easy, straight-forward implementation for safely parsing and rendering HTML.

<Interweave />​

The Interweave component has the additional benefit of utilizing filters, matchers, and callbacks.

import { Interweave } from 'interweave';

<Interweave content="This string contains <b>HTML</b> and will safely be rendered!" />;

<Interweave
    content="This contains a URL, https://github.com/milesj/interweave, and a hashtag, #interweave, that will be converted to an anchor link!"
    matchers={[new UrlMatcher('url'), new HashtagMatcher('hashtag')]}
/>;

<Markup />​

Unlike the Interweave component, the Markup component does not support matchers, filters, or callbacks. This component is preferred when rendering strings that contain HTML is the only use case.

import { Markup } from 'interweave';

<Markup content="This string <b>contains</b> HTML." />;

Props​

Markup & Interweave

  • allowAttributes (boolean) - Disable filtering and allow all non-banned HTML attributes.
  • allowElements (boolean) - Disable filtering and allow all non-banned/blocked HTML elements to be rendered.
  • allowList (string[]) - List of HTML tag names to allow and render. Defaults to the ALLOWED_TAG_LIST constant.
  • attributes (Record<string, boolean | number | object | string>) - HTML attributes to pass to the wrapping element.
  • blockList (string[]) - List of HTML tag names to disallow and not render. Overrides allow list.
  • containerTagName (string) - The container element to parse content in. Applies browser semantic rules and overrides tagName.
  • className (string) - CSS class name to pass to the wrapping element.
  • content (string) - The string to render and apply matchers and filters to. Supports HTML.
  • disableLineBreaks (boolean) - Disables automatic line break conversion.
  • emptyContent (Node) - React node to render if no content was rendered.
  • escapeHtml (boolean) - Escape all HTML in the content before parsing.
  • noHtml (boolean) - Strips HTML tags from the content string while parsing. Also strips HTML generated by matchers.
  • noHtmlExceptMatchers (boolean) - Like the former, but allows HTML generated by matchers.
  • noWrap (boolean) - Do not wrap the content in an HTML element (uses React fragments).
  • tagName (string) - The HTML element tag name to wrap the output with. Defaults to "span".
  • transform (func) - Callback that fires during parsing. Is passed the parsed DOM node, and can return an element, null to skip the node, or undefined to use the default element.
  • transformOnlyAllowList (boolean) - Disables the transform function for tags not present in the allowList.

Interweave only

  • disableFilters (boolean) - Disables all filters.
  • disableMatchers (boolean) - Disables all matchers.
  • filters (Filter[]) - Filters to apply to this instance.
  • matchers (Matcher[]) - Matchers to apply to this instance.
  • onBeforeParse (func) - Callback that fires before parsing. Is passed the source string and must return a string.
  • onAfterParse (func) - Callback that fires after parsing. Is passed an array of strings/elements and must return an array.