hiccup

Fast library for rendering HTML in Clojure

2,720

177

2,720

View on GitHub

Top Related Projects

reagent

4,811

A minimalistic ClojureScript interface to React.js

re-frame

5,463

A ClojureScript framework for building user interfaces, leveraging React

rum

1,810

Simple, decomplected, isomorphic HTML UI library for Clojure and ClojureScript

hoplon

1,024

Simple and powerful tool for building web apps out of highly composable elements in ClojureScript.

lein-figwheel

2,879

Figwheel builds your ClojureScript code and hot loads it into the browser as you are coding!

Quick Overview

Hiccup is a Clojure library for representing HTML as Clojure data structures. It allows developers to generate HTML using Clojure vectors and maps, providing a concise and expressive way to create web content programmatically. Hiccup is widely used in Clojure web development projects.

Pros

Simple and intuitive syntax for representing HTML
Seamless integration with Clojure's data structures and functions
Excellent performance due to its lightweight nature
Extensible through custom rendering functions

Cons

Limited to Clojure ecosystem, not usable in other languages
Requires learning a new syntax for HTML representation
May be overkill for simple HTML generation tasks
Potential for decreased readability in complex nested structures

Code Examples

Basic HTML generation:

(require '[hiccup.core :as hiccup])

(hiccup/html [:div {:class "greeting"} "Hello, World!"])
;; Output: "<div class=\"greeting\">Hello, World!</div>"

Nested elements and attributes:

(hiccup/html
  [:ul
    [:li {:class "item"} "First item"]
    [:li {:class "item"} "Second item"]
    [:li {:class "item"} "Third item"]])
;; Output: "<ul><li class=\"item\">First item</li><li class=\"item\">Second item</li><li class=\"item\">Third item</li></ul>"

Using Clojure functions to generate dynamic content:

(defn generate-list-items [items]
  (for [item items]
    [:li item]))

(hiccup/html
  [:ul
    (generate-list-items ["Apple", "Banana", "Cherry"])])
;; Output: "<ul><li>Apple</li><li>Banana</li><li>Cherry</li></ul>"

Getting Started

To use Hiccup in your Clojure project, add the following dependency to your project.clj file:

[hiccup "1.0.5"]

Then, in your Clojure code, require the Hiccup namespace:

(ns your-namespace
  (:require [hiccup.core :as hiccup]))

;; Now you can use Hiccup to generate HTML
(hiccup/html [:h1 "Welcome to Hiccup!"])

Competitor Comparisons

reagent

4,811

A minimalistic ClojureScript interface to React.js

Pros of Reagent

Reactive programming model for efficient UI updates
Integrates seamlessly with React ecosystem
Supports component-based architecture

Cons of Reagent

Steeper learning curve for developers new to reactive programming
More complex setup compared to Hiccup's simplicity
Potential performance overhead for small, static pages

Code Comparison

Hiccup:

(defn my-component [name]
  [:div
    [:h1 "Hello, " name "!"]
    [:p "Welcome to Hiccup."]])

Reagent:

(defn my-component [name]
  (let [greeting (r/atom "Hello")]
    (fn []
      [:div
        [:h1 @greeting ", " name "!"]
        [:p "Welcome to Reagent."]])))

Summary

Hiccup is a simple and lightweight library for generating HTML in Clojure, ideal for server-side rendering and static content. Reagent, built on top of React, offers a more powerful and dynamic approach to building user interfaces, particularly suited for complex, interactive web applications. While Hiccup excels in simplicity and ease of use, Reagent provides a robust framework for creating reactive, component-based UIs with efficient update mechanisms.

clojurescript

9,272

Clojure to JS compiler

Pros of ClojureScript

Compiles Clojure to JavaScript, enabling full-stack Clojure development
Provides access to the entire JavaScript ecosystem
Offers advanced optimizations for production builds

Cons of ClojureScript

Steeper learning curve for developers new to Clojure
Larger compilation overhead compared to Hiccup
More complex setup and tooling requirements

Code Comparison

Hiccup (HTML generation):

(html [:div#content
       [:h1 {:class "title"} "Hello, World!"]
       [:p "Welcome to my website."]])

ClojureScript (React component):

(defn hello-world []
  [:div#content
   [:h1.title "Hello, World!"]
   [:p "Welcome to my website."]])

Key Differences

Hiccup is primarily used for server-side HTML generation in Clojure
ClojureScript enables client-side development with Clojure syntax
Hiccup is more lightweight and focused on HTML templating
ClojureScript offers a complete solution for building web applications

Use Cases

Hiccup: Server-side rendering, static site generation, email templates
ClojureScript: Single-page applications, interactive UIs, full-stack Clojure projects

Community and Ecosystem

Hiccup: Widely used in Clojure web development, many extensions available
ClojureScript: Large ecosystem, active community, integration with popular JavaScript libraries

re-frame

5,463

A ClojureScript framework for building user interfaces, leveraging React

Pros of re-frame

Provides a complete architecture for building SPAs in ClojureScript
Implements a unidirectional data flow pattern, making state management more predictable
Offers built-in effects and coeffects system for side-effect management

Cons of re-frame

Steeper learning curve due to its comprehensive architecture
More opinionated, which may limit flexibility in certain scenarios
Requires additional setup and boilerplate compared to simpler libraries

Code Comparison

re-frame (event handler):

(re-frame/reg-event-db
 :initialize-db
 (fn [_ _]
   {:name "re-frame"}))

Hiccup (HTML generation):

(hiccup/html
 [:div
  [:h1 "Hello, Hiccup!"]])

Key Differences

re-frame is a full-featured framework for building SPAs, while Hiccup is a library for generating HTML
re-frame focuses on application architecture and state management, whereas Hiccup is primarily concerned with HTML rendering
Hiccup can be used within re-frame for view rendering, making them complementary rather than mutually exclusive

Use Cases

Choose re-frame for complex SPAs requiring robust state management
Opt for Hiccup when you need a simple, lightweight solution for generating HTML in Clojure(Script) projects

rum

1,810

Simple, decomplected, isomorphic HTML UI library for Clojure and ClojureScript

Pros of Rum

More comprehensive framework with built-in state management and event handling
Supports server-side rendering out of the box
Offers better performance optimization techniques

Cons of Rum

Steeper learning curve due to more complex API
Less flexibility for integration with other libraries or frameworks
Larger codebase and potentially more overhead

Code Comparison

Hiccup:

(defn my-component [name]
  [:div
    [:h1 (str "Hello, " name "!")]
    [:p "Welcome to Hiccup"]])

Rum:

(rum/defc my-component [name]
  [:div
    [:h1 (str "Hello, " name "!")]
    [:p "Welcome to Rum"]])

Both Hiccup and Rum use a similar syntax for defining components, with Rum requiring the rum/defc macro. Rum components are more powerful, supporting local state and lifecycle methods, while Hiccup focuses on simple HTML generation.

Hiccup is lightweight and easy to integrate into existing projects, making it ideal for simple templating needs. Rum, on the other hand, provides a full-featured framework for building complex web applications with React-like components and state management.

Choose Hiccup for straightforward HTML generation in Clojure projects, and Rum for building more complex, stateful web applications with a React-inspired approach.

hoplon

1,024

Simple and powerful tool for building web apps out of highly composable elements in ClojureScript.

Pros of Hoplon

Full-stack framework for building web applications
Reactive programming model with cell-based state management
Seamless integration of client and server-side code

Cons of Hoplon

Steeper learning curve due to its unique approach
Less widely adopted compared to Hiccup
May be overkill for simple projects or static sites

Code Comparison

Hiccup example:

(html [:div {:class "greeting"}
       [:h1 "Hello, World!"]
       [:p "Welcome to Hiccup"]])

Hoplon example:

(page "index.html"
  (html
    (body
      (div :class "greeting"
        (h1 "Hello, World!")
        (p "Welcome to Hoplon")))))

Key Differences

Hiccup focuses on HTML generation using Clojure data structures
Hoplon provides a more comprehensive framework for building interactive web applications
Hiccup is simpler and more lightweight, ideal for server-side rendering
Hoplon offers a reactive programming model, suitable for complex client-side applications

Use Cases

Choose Hiccup for simple HTML generation or server-side rendering
Opt for Hoplon when building complex, interactive single-page applications
Hiccup is great for integrating with other Clojure web frameworks
Hoplon shines in projects requiring real-time updates and complex state management

lein-figwheel

2,879

Figwheel builds your ClojureScript code and hot loads it into the browser as you are coding!

Pros of lein-figwheel

Provides hot code reloading for ClojureScript projects, enabling rapid development
Offers a built-in REPL for interactive development and debugging
Automatically manages asset compilation and dependency tracking

Cons of lein-figwheel

More complex setup and configuration compared to Hiccup's simplicity
Focused on ClojureScript development, while Hiccup is more versatile for general HTML generation
Steeper learning curve for beginners due to its advanced features

Code Comparison

Hiccup (HTML generation):

(html [:div#content
       [:h1 {:class "title"} "Hello, World!"]
       [:p "Welcome to my website."]])

lein-figwheel (ClojureScript development):

(defproject my-project "0.1.0-SNAPSHOT"
  :dependencies [[org.clojure/clojure "1.10.0"]
                 [org.clojure/clojurescript "1.10.773"]]
  :plugins [[lein-figwheel "0.5.20"]])

While Hiccup focuses on generating HTML using Clojure data structures, lein-figwheel is a tool for ClojureScript development that provides features like hot reloading and REPL integration. Hiccup is simpler to use for basic HTML generation, while lein-figwheel offers a more comprehensive development environment for ClojureScript projects.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Hiccup

Hiccup is a library for representing HTML in Clojure. It uses vectors to represent elements, and maps to represent an element's attributes.

Install

Add the following dependency to your deps.edn file:

hiccup/hiccup {:mvn/version "2.0.0-RC5"}

Or to your Leiningen project.clj file:

[hiccup "2.0.0-RC5"]

Documentation

Syntax

Here is a basic example of Hiccup syntax:

user=> (require '[hiccup2.core :as h])
nil
user=> (str (h/html [:span {:class "foo"} "bar"]))
"<span class=\"foo\">bar</span>"

The first element of the vector is used as the element name. The second attribute can optionally be a map, in which case it is used to supply the element's attributes. Every other element is considered part of the tag's body.

Hiccup is intelligent enough to render different HTML elements in different ways, in order to accommodate browser quirks:

user=> (str (h/html [:script]))
"<script></script>"
user=> (str (h/html [:p]))
"<p />"

And provides a CSS-like shortcut for denoting id and class attributes:

user=> (str (h/html [:div#foo.bar.baz "bang"]))
"<div id=\"foo\" class=\"bar baz\">bang</div>"

If the body of the element is a seq, its contents will be expanded out into the element body. This makes working with forms like map and for more convenient:

user=> (str (h/html [:ul
                     (for [x (range 1 4)]
                       [:li x])]))
"<ul><li>1</li><li>2</li><li>3</li></ul>"

Strings are automatically escaped:

user=> (str (h/html [:p "Tags in HTML are written with <>"]))
"<p>Tags in HTML are written with &lt;&gt;</p>"

To bypass this, use the hiccup2.core/raw function:

user=> (str (h/html [:p (h/raw "Hello <em>World</em>")]))
"<p>Hello <em>World</em></p>"

This can also be used for doctype declarations:

user=> (str (h/html (h/raw "<!DOCTYPE html>") [:html {:lang "en"}]))
"<!DOCTYPE html><html lang=\"en\"></html>"

Differences between Hiccup 1 and 2

In brief: Hiccup 1 doesn't escape strings by default, while Hiccup 2 does. They occupy different namespaces to ensure backward compatibility.

In Hiccup 1, you use the h function to escape a string - that is, ensure that unsafe characters like <, > and & are converted into their equivalent entity codes:

(h1/html [:div "Username: " (h1/h username)])

In Hiccup 2 strings are escaped automatically, but the return value from the html macro is a RawString, rather than a String. This ensures that the html macro can still be nested.

(str (h2/html [:div "Username: " username]))

It's recommended to use Hiccup 2 where possible, particularly if your app handles user data. Use of the non-core namespaces, such as hiccup.page, should be avoided with Hiccup 2.

License

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot