Data

Tools

Indexes

Applications

Experiments

Ruby

A summary of data about the Ruby ecosystem.

https://github.com/flavorjones/loofah

Ruby library for HTML/XML transformation and sanitization
https://github.com/flavorjones/loofah

Keywords from Contributors

activerecord activejob mvc rubygems sinatra rspec rack debugger background-jobs ruby-gem

Last synced: about 24 hours ago
JSON representation

Repository metadata

Ruby library for HTML/XML transformation and sanitization

README.md

Loofah

Status

ci
Tidelift dependencies

Description

Loofah is a general library for manipulating and transforming HTML/XML documents and fragments, built on top of Nokogiri.

Loofah also includes some HTML sanitizers based on html5lib's safelist, which are a specific application of the general transformation functionality.

Active Record extensions for HTML sanitization are available in the loofah-activerecord gem.

Features

  • Easily write custom transformations for HTML and XML
  • Common HTML sanitizing transformations are built-in:
    • Strip unsafe tags, leaving behind only the inner text.
    • Prune unsafe tags and their subtrees, removing all traces that they ever existed.
    • Escape unsafe tags and their subtrees, leaving behind lots of < and > entities.
    • Whitewash the markup, removing all attributes and namespaced nodes.
  • Other common HTML transformations are built-in:
    • Add the nofollow attribute to all hyperlinks.
    • Add the target=_blank attribute to all hyperlinks.
    • Remove unprintable characters from text nodes.
  • Some specialized HTML transformations are also built-in:
    • Where <br><br> exists inside a p tag, close the p and open a new one.
  • Format markup as plain text, with (or without) sensible whitespace handling around block elements.
  • Replace Rails's strip_tags and sanitize view helper methods.

Compare and Contrast

Loofah is both:

  • a general framework for transforming XML, XHTML, and HTML documents
  • a specific toolkit for HTML sanitization

General document transformation

Loofah tries to make it easy to write your own custom scrubbers for whatever document transformation you need. You don't like the built-in scrubbers? Build your own, like a boss.

HTML sanitization

Another Ruby library that provides HTML sanitization is rgrove/sanitize, another library built on top of Nokogiri, which provides a bit more flexibility on the tags and attributes being scrubbed.

You may also want to look at rails/rails-html-sanitizer which is built on top of Loofah and provides some useful extensions and additional flexibility in the HTML sanitization.

The Basics

Loofah wraps Nokogiri in a loving embrace. Nokogiri is a stable, well-maintained parser for XML, HTML4, and HTML5.

Loofah implements the following classes:

  • Loofah::HTML5::Document
  • Loofah::HTML5::DocumentFragment
  • Loofah::HTML4::Document (aliased as Loofah::HTML::Document for now)
  • Loofah::HTML4::DocumentFragment (aliased as Loofah::HTML::DocumentFragment for now)
  • Loofah::XML::Document
  • Loofah::XML::DocumentFragment

These document and fragment classes are subclasses of the similarly-named Nokogiri classes Nokogiri::HTML5::Document et al.

Loofah also implements Loofah::Scrubber, which represents the document transformation, either by wrapping
a block,

span2div = Loofah::Scrubber.new do |node|
  node.name = "div" if node.name == "span"
end

or by implementing a method.

Side Note: Fragments vs Documents

Generally speaking, unless you expect to have a DOCTYPE and a single root node, you don't have a document, you have a fragment. For HTML, another rule of thumb is that documents have html and body tags, and fragments usually do not.

HTML fragments should be parsed with Loofah.html5_fragment or Loofah.html4_fragment. The result won't be wrapped in html or body tags, won't have a DOCTYPE declaration, head elements will be silently ignored, and multiple root nodes are allowed.

HTML documents should be parsed with Loofah.html5_document or Loofah.html4_document. The result will have a DOCTYPE declaration, along with html, head and body tags.

XML fragments should be parsed with Loofah.xml_fragment. The result won't have a DOCTYPE declaration, and multiple root nodes are allowed.

XML documents should be parsed with Loofah.xml_document. The result will have a DOCTYPE declaration and a single root node.

Side Note: HTML4 vs HTML5

⚠ HTML5 functionality is not available on JRuby, or with versions of Nokogiri < 1.14.0.

Currently, Loofah's methods Loofah.document and Loofah.fragment are aliases to .html4_document and .html4_fragment, which use Nokogiri's HTML4 parser. (Similarly, Loofah::HTML::Document and Loofah::HTML::DocumentFragment are aliased to Loofah::HTML4::Document and Loofah::HTML4::DocumentFragment.)

Please note that in a future version of Loofah, these methods and classes may switch to using Nokogiri's HTML5 parser and classes on platforms that support it [1].

We strongly recommend that you explicitly use .html5_document or .html5_fragment unless you know of a compelling reason not to. If you are sure that you need to use the HTML4 parser, you should explicitly call .html4_document or .html4_fragment to avoid breakage in a future version.

[1]: [feature request] HTML5 parser for JRuby implementation · Issue #2227 · sparklemotion/nokogiri

Loofah::HTML5::Document and Loofah::HTML5::DocumentFragment

These classes are subclasses of Nokogiri::HTML5::Document and Nokogiri::HTML5::DocumentFragment.

The module methods Loofah.html5_document and Loofah.html5_fragment will parse either an HTML document and an HTML fragment, respectively.

Loofah.html5_document(unsafe_html).is_a?(Nokogiri::HTML5::Document)         # => true
Loofah.html5_fragment(unsafe_html).is_a?(Nokogiri::HTML5::DocumentFragment) # => true

Loofah injects a scrub! method, which takes either a symbol (for built-in scrubbers) or a Loofah::Scrubber object (for custom scrubbers), and modifies the document in-place.

Loofah overrides to_s to return HTML:

unsafe_html = "ohai! <div>div is safe</div> <script>but script is not</script>"

doc = Loofah.html5_fragment(unsafe_html).scrub!(:prune)
doc.to_s    # => "ohai! <div>div is safe</div> "

and text to return plain text:

doc.text    # => "ohai! div is safe "

Also, to_text is available, which does the right thing with whitespace around block-level and line break elements.

doc = Loofah.html5_fragment("<h1>Title</h1><div>Content<br>Next line</div>")
doc.text    # => "TitleContentNext line"            # probably not what you want
doc.to_text # => "\nTitle\n\nContent\nNext line\n"  # better

Loofah::HTML4::Document and Loofah::HTML4::DocumentFragment

These classes are subclasses of Nokogiri::HTML4::Document and Nokogiri::HTML4::DocumentFragment.

The module methods Loofah.html4_document and Loofah.html4_fragment will parse either an HTML document and an HTML fragment, respectively.

Loofah.html4_document(unsafe_html).is_a?(Nokogiri::HTML4::Document)         # => true
Loofah.html4_fragment(unsafe_html).is_a?(Nokogiri::HTML4::DocumentFragment) # => true

Loofah::XML::Document and Loofah::XML::DocumentFragment

These classes are subclasses of Nokogiri::XML::Document and Nokogiri::XML::DocumentFragment.

The module methods Loofah.xml_document and Loofah.xml_fragment will parse an XML document and an XML fragment, respectively.

Loofah.xml_document(bad_xml).is_a?(Nokogiri::XML::Document)         # => true
Loofah.xml_fragment(bad_xml).is_a?(Nokogiri::XML::DocumentFragment) # => true

Nodes and Node Sets

Nokogiri's Node and NodeSet classes also get a scrub! method, which makes it easy to scrub subtrees.

The following code will apply the employee_scrubber only to the employee nodes (and their subtrees) in the document:

Loofah.xml_document(bad_xml).xpath("//employee").scrub!(employee_scrubber)

And this code will only scrub the first employee node and its subtree:

Loofah.xml_document(bad_xml).at_xpath("//employee").scrub!(employee_scrubber)

Loofah::Scrubber

A Scrubber wraps up a block (or method) that is run on a document node:

# change all <span> tags to <div> tags
span2div = Loofah::Scrubber.new do |node|
  node.name = "div" if node.name == "span"
end

This can then be run on a document:

Loofah.html5_fragment("<span>foo</span><p>bar</p>").scrub!(span2div).to_s
# => "<div>foo</div><p>bar</p>"

Scrubbers can be run on a document in either a top-down traversal (the default) or bottom-up. Top-down scrubbers can optionally return Scrubber::STOP to terminate the traversal of a subtree. Read below and in the Loofah::Scrubber class for more detailed usage.

Here's an XML example:

# remove all <employee> tags that have a "deceased" attribute set to true
bring_out_your_dead = Loofah::Scrubber.new do |node|
  if node.name == "employee" and node["deceased"] == "true"
    node.remove
    Loofah::Scrubber::STOP # don't bother with the rest of the subtree
  end
end
Loofah.xml_document(File.read('plague.xml')).scrub!(bring_out_your_dead)

Built-In HTML Scrubbers

Loofah comes with a set of sanitizing scrubbers that use html5lib's safelist algorithm:

doc = Loofah.html5_document(input)
doc.scrub!(:strip)       # replaces unknown/unsafe tags with their inner text
doc.scrub!(:prune)       #  removes unknown/unsafe tags and their children
doc.scrub!(:escape)      #  escapes unknown/unsafe tags, like this: &lt;script&gt;
doc.scrub!(:whitewash)   #  removes unknown/unsafe/namespaced tags and their children,
                         #          and strips all node attributes

Loofah also comes with built-in scrubers for some common transformation tasks:

doc.scrub!(:nofollow)          # adds rel="nofollow" attribute to links
doc.scrub!(:noopener)          # adds rel="noopener" attribute to links
doc.scrub!(:noreferrer)        # adds rel="noreferrer" attribute to links
doc.scrub!(:unprintable)       # removes unprintable characters from text nodes
doc.scrub!(:targetblank)       # adds target="_blank" attribute to links
doc.scrub!(:double_breakpoint) # where `<br><br>` appears in a `p` tag, close the `p` and open a new one

See Loofah::Scrubbers for more details and example usage.

Chaining Scrubbers

You can chain scrubbers:

Loofah.html5_fragment("<span>hello</span> <script>alert('OHAI')</script>") \
      .scrub!(:prune) \
      .scrub!(span2div).to_s
# => "<div>hello</div> "

Shorthand

The class methods Loofah.scrub_html5_fragment and Loofah.scrub_html5_document (and the corresponding HTML4 methods) are shorthand.

These methods:

Loofah.scrub_html5_fragment(unsafe_html, :prune)
Loofah.scrub_html5_document(unsafe_html, :prune)
Loofah.scrub_html4_fragment(unsafe_html, :prune)
Loofah.scrub_html4_document(unsafe_html, :prune)
Loofah.scrub_xml_fragment(bad_xml, custom_scrubber)
Loofah.scrub_xml_document(bad_xml, custom_scrubber)

do the same thing as (and arguably semantically clearer than):

Loofah.html5_fragment(unsafe_html).scrub!(:prune)
Loofah.html5_document(unsafe_html).scrub!(:prune)
Loofah.html4_fragment(unsafe_html).scrub!(:prune)
Loofah.html4_document(unsafe_html).scrub!(:prune)
Loofah.xml_fragment(bad_xml).scrub!(custom_scrubber)
Loofah.xml_document(bad_xml).scrub!(custom_scrubber)

View Helpers

Loofah has two "view helpers": Loofah::Helpers.sanitize and Loofah::Helpers.strip_tags, both of which are drop-in replacements for the Rails Action View helpers of the same name.

These are not required automatically. You must require loofah/helpers to use them.

Requirements

  • Nokogiri >= 1.5.9

Installation

Unsurprisingly:

gem install loofah

Requirements:

  • Ruby >= 2.5

Support

The bug tracker is available here:

And the mailing list is on Google Groups:

Consider subscribing to Tidelift which provides license assurances and timely security notifications for your open source dependencies, including Loofah. Tidelift subscriptions also help the Loofah maintainers fund our automated testing which in turn allows us to ship releases, bugfixes, and security updates more often.

Security

See SECURITY.md for vulnerability reporting details.

Related Links

Authors

Featuring code contributed by:

And a big shout-out to Corey Innis for the name, and feedback on the API.

Thank You

The following people have generously funded Loofah with financial sponsorship:

  • Bill Harding
  • Sentry @getsentry

Historical Note

This library was once named "Dryopteris", which was a very bad name that nobody could spell properly.

License

Distributed under the MIT License. See MIT-LICENSE.txt for details.

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 2 days ago

Total Commits: 734
Total Committers: 64
Avg Commits per committer: 11.469
Development Distribution Score (DDS): 0.172

Commits in past year: 9
Committers in past year: 2
Avg Commits per committer in past year: 4.5
Development Distribution Score (DDS) in past year: 0.111

Name Email Commits
Mike Dalessio m****e@c****t 608
Bryan Helmkamp b****n@b****m 15
Olle Jonsson o****n@g****m 14
Juanito Fatas k****0@g****m 10
Timm k****h@g****m 9
Jose Colella j****a@g****m 4
Orien Madgwick _@o****o 3
Ken Dreyer k****r@k****m 3
Aaron Patterson a****n@g****m 3
Juanito Fatas j****s@s****m 3
m-nakamura145 m****5@g****m 2
Tarcisio Ferraz t****z@p****m 2
Adam Sokolnicki a****i@g****m 2
James Adam j****s@l****m 2
Jun Aruga j****a@r****m 2
MothOnMars m****s@g****m 2
Nick DeSteffen n****n@g****m 2
Niko Roberts n****o@t****m 2
Brendon Muir b****n@s****z 1
Ben Atkins b****z@g****m 1
Bao Pham g****m@g****m 1
Anton Rieder 1****r 1
Andrey Nering a****g@g****m 1
Andrew Nesbitt a****z@g****m 1
Matt Swanson m****n@s****m 1
Bill Chaney b****l@a****o 1
Fabian Winkler 1
Jen-Mei Wu and Tommy Devol p****y@i****m 1
Laurent Cobos l****t@1****r 1
Rafael Mendonça França r****a@p****r 1
and 34 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 3 months ago

Total issues: 48
Total pull requests: 102
Average time to close issues: 6 months
Average time to close pull requests: about 1 month
Total issue authors: 37
Total pull request authors: 38
Average comments per issue: 4.06
Average comments per pull request: 1.75
Merged pull request: 73
Bot issues: 0
Bot pull requests: 2

Past year issues: 1
Past year pull requests: 16
Past year average time to close issues: N/A
Past year average time to close pull requests: 13 days
Past year issue authors: 1
Past year pull request authors: 4
Past year average comments per issue: 0.0
Past year average comments per pull request: 0.88
Past year merged pull request: 10
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/flavorjones/loofah

Top Issue Authors

  • flavorjones (9)
  • stefannibrasil (2)
  • bbugh (2)
  • epinault (2)
  • rocketedaway (1)
  • lessless (1)
  • unikitty37 (1)
  • miguelperez (1)
  • jarkko (1)
  • th0r (1)
  • davidjstein (1)
  • piyush-ally (1)
  • jmjohnson (1)
  • puneet-sutar (1)
  • brendon (1)

Top Pull Request Authors

  • flavorjones (48)
  • lazyatom (4)
  • m-nakamura145 (4)
  • factcondenser (2)
  • fnando (2)
  • dependabot-preview[bot] (2)
  • troym9731 (2)
  • nick-desteffen (2)
  • lucyxiang (2)
  • JuanitoFatas (2)
  • josecolella (2)
  • Earlopain (2)
  • headius (2)
  • andrew (2)
  • sampokuokkanen (1)

Top Issue Labels

  • user-help (4)
  • allowlist (3)
  • feature (3)
  • discussion (2)
  • will-close (2)
  • needs more information (2)
  • scrubbers (1)
  • blocked (1)

Top Pull Request Labels

  • dependencies (2)
  • needs more information (1)
  • pr-under-review (1)

Package metadata

gem.coop: loofah

Loofah is a general library for manipulating and transforming HTML/XML documents and fragments, built on top of Nokogiri. Loofah also includes some HTML sanitizers based on `html5lib`'s safelist, which are a specific application of the general transformation functionality.

rubygems.org: loofah

Loofah is a general library for manipulating and transforming HTML/XML documents and fragments, built on top of Nokogiri. Loofah also includes some HTML sanitizers based on `html5lib`'s safelist, which are a specific application of the general transformation functionality.

proxy.golang.org: github.com/flavorjones/loofah

  • Homepage:
  • Documentation: https://pkg.go.dev/github.com/flavorjones/loofah#section-documentation
  • Licenses: mit
  • Latest release: v2.25.0+incompatible (published 3 months ago)
  • Last Synced: 2026-03-02T09:01:17.411Z (2 days ago)
  • Versions: 59
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Stargazers count: 2.112%
    • Forks count: 2.341%
    • Average: 6.208%
    • Dependent packages count: 9.576%
    • Dependent repos count: 10.802%
ubuntu-22.04: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Licenses:
  • Latest release: 2.13.0-2 (published 19 days ago)
  • Last Synced: 2026-02-13T13:20:07.398Z (19 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-24.04: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Licenses:
  • Latest release: 2.22.0-1 (published 26 days ago)
  • Last Synced: 2026-02-06T15:30:16.829Z (26 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
debian-10: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Documentation: https://packages.debian.org/buster/ruby-loofah
  • Licenses:
  • Latest release: 2.2.3-1+deb10u1 (published 21 days ago)
  • Last Synced: 2026-02-13T04:22:47.632Z (19 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-20.04: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Licenses:
  • Latest release: 2.4.0+dfsg-1 (published 19 days ago)
  • Last Synced: 2026-02-13T07:17:16.449Z (19 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-23.10: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Licenses:
  • Latest release: 2.21.3-1 (published 19 days ago)
  • Last Synced: 2026-02-13T18:24:39.199Z (19 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
debian-12: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Documentation: https://packages.debian.org/bookworm/ruby-loofah
  • Licenses:
  • Latest release: 2.19.1-1 (published 20 days ago)
  • Last Synced: 2026-02-12T23:34:42.749Z (20 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
debian-11: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Documentation: https://packages.debian.org/bullseye/ruby-loofah
  • Licenses:
  • Latest release: 2.7.0+dfsg-1 (published 22 days ago)
  • Last Synced: 2026-02-13T08:21:56.844Z (19 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-24.10: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Licenses:
  • Latest release: 2.22.0-1 (published 23 days ago)
  • Last Synced: 2026-02-09T16:53:11.377Z (23 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
ubuntu-23.04: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Licenses:
  • Latest release: 2.19.1-1 (published 21 days ago)
  • Last Synced: 2026-02-11T06:42:57.044Z (21 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
debian-13: ruby-loofah

  • Homepage: https://github.com/flavorjones/loofah
  • Documentation: https://packages.debian.org/trixie/ruby-loofah
  • Licenses:
  • Latest release: 2.24.0-1 (published 20 days ago)
  • Last Synced: 2026-02-13T13:17:21.272Z (19 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%

Dependencies

loofah.gemspec rubygems
  • hoe-markdown ~> 1.3 development
  • json ~> 2.2 development
  • minitest ~> 5.14 development
  • rake ~> 13.0 development
  • rdoc >= 4.0, < 7 development
  • rr ~> 1.2.0 development
  • rubocop ~> 1.1 development
  • crass ~> 1.0.2
  • nokogiri >= 1.5.9
.github/workflows/ci.yml actions
  • actions/checkout v2 composite
  • ruby/setup-ruby v1 composite
Gemfile rubygems
  • rubocop ~> 1.1 development
  • rubocop-minitest = 0.29.0 development
  • rubocop-packaging = 0.5.2 development
  • rubocop-performance = 1.16.0 development
  • rubocop-rake = 0.6.0 development
  • rubocop-shopify = 2.12.0 development

Score: 32.88001609888285