Hiccup is a Clojure library that renders HTML from vector and map data structures, giving developers a composable, programmatic way to generate markup without a separate template language.
What is Hiccup?
Hiccup is a library for representing HTML in Clojure, created by James Reeves and distributed under the Eclipse Public License. It takes Clojure vectors (for elements) and maps (for attributes) as input and produces HTML strings as output, with automatic string escaping in version 2.0.0. The library runs on any Clojure implementation and integrates with standard Clojure build tools via deps.edn or Leiningen. It is actively maintained and documented through a wiki and API docs.
Key Features
- Vector-based syntax — Elements are written as vectors: the first item is the tag name, an optional map supplies attributes, and the remaining items form the body. Example:
[:span {:class "foo"} "bar"]renders as<span class="foo">bar</span>. - CSS-style id and class shortcuts —
[:div#foo.bar.baz "bang"]renders as<div id="foo" class="bar baz">bang</div>, reducing attribute boilerplate. - Automatic string escaping — In Hiccup 2, strings are escaped by default to prevent XSS, and the
hiccup2.core/rawfunction opts out for trusted content like a doctype. - Seq expansion — Any seq in the body is flattened into the element, so you can generate lists with
(for [x (range 1 4)] [:li x])directly. - Browser-quirk handling — Different tags render differently:
[:script]becomes<script></script>while[:p]becomes<p />, matching browser expectations. - Backward-compatible namespaces — Hiccup 1 and Hiccup 2 coexist in separate namespaces (
hiccup.corevshiccup2.core), enabling incremental migration. - Open-source license — Released under the Eclipse Public License 1.0 or later, permitting use in commercial projects.
Who should use Hiccup?
- Clojure web developers who want server-side rendering in Ring or Compojure apps can generate HTML directly from Clojure data structures.
- Library authors building templating engines, static site generators, or HTML-emitting tools can use Hiccup as a foundation for composable markup.
- Teams upgrading from Hiccup 1 can adopt Hiccup 2 for auto-escaping (especially when handling user input) without breaking existing code.
Use cases
- Server-side rendering: Build complete HTML pages in pure Clojure functions, using
forandmapto generate tables, lists, and other repeated elements. - Email and notification content: Produce escaped HTML strings for emails or admin notices, keeping user-generated content safe from injection.
- REPL-driven prototyping: Quickly experiment with markup by calling the
htmlmacro in a REPL; the returnedRawStringnests cleanly in largerhtmlcalls.
FAQ
Is Hiccup free?
Hiccup is open source and distributed under the Eclipse Public License, version 1.0 or later, so you can use it in commercial projects without licensing fees.
What is the difference between Hiccup 1 and Hiccup 2?
Hiccup 1 does not escape strings by default; you must wrap untrusted text with the h function. Hiccup 2 escapes all strings automatically and returns a RawString from the html macro, which enables nesting. The two versions use different namespaces (hiccup.core vs hiccup2.core), so they can coexist.
How does Hiccup handle raw HTML?
Use hiccup2.core/raw to bypass escaping for trusted content, such as a doctype declaration or an inline <em> tag. For example, (h/raw "<!DOCTYPE html>") emits the literal string.
Can I use Hiccup with ClojureScript?
Hiccup is written in Clojure and works anywhere Clojure runs, including ClojureScript projects, making it suitable for both server-side and client-side HTML generation.
