Liking cljdoc? Tell your friends :D

Herb is a CSS styling library for Clojurescript, built using Garden, whose main focus is on component level styling using functions.

Requirements

Herb requires at least Clojure 1.9.0 and ClojureScript 1.9.542 due to use of clojure.spec.alpha to validate macro input.

Quick start

Clojars Project

(ns user
  (:require [herb.core :refer [<class]]))

(defn style []
  {:background "red"})

(defn component
  [:div {:class (<class style)}])

Herb has two main macros, <class and <id, these macros takes a function that returns a Garden style map, and returns a classname/id based on the functions fully qualified name, in this case user/style.

The style is injected into the DOM when any one of Herb's macros are called.

Pass arguments:

(ns user
  (:require [herb.core :refer [<class]]))

(defn style
  [color]
  {:color color})

(defn component []
  [:div {:class (<class style "red")}])

Extend existing functions:

(ns user
  (:require [herb.core :refer [<class]]))

(defn button-style [text-color]
  {:display "inline-block"
   :color text-color
   :text-transform "uppercase"
   :cursor "pointer"
   :padding (px 12)})

(defn red-button-style []
  ^{:extend [button-style "white"]}
  {:background-color "red"})

(defn button []
  [:button {:class (<class red-button-style)}])

Garden is used to translate the style map to CSS, which enables most of Gardens functionality, so familiarizing yourself with its features is a good idea.

Refer to the tutorial for a full overview and examples of Herbs features.

Advanced optimizations

During a production build add this to the :compiler config :closure-defines {"goog.DEBUG" false}. This flag tells Herb to minify styles, remove unneeded style element attributes, and ensure anonymous functions gets the correct minified name.

Debugging advanced compilation

During advanced compilation Herb minify styles and removes the data-herb attribute. If you need to debug production build it can be helpful to see the function namespaces unmunged to get a clearer image of what is happening.

To do this remove the goog.DEBUG false from production build and enable :pseudo-names:

:cljsbuild {:builds {:min {:source-paths ["src" "env/prod"]
                           :compiler {:pseudo-names true
                                      :optimizations :advanced
                                      ...
                                      }}

That way you will see both full classnames and the namespace reflected in the data-herb HTML attribute.

Development

Start figwheel main with the development build

lein fig:build

Figwheel-main will automatically push cljs changes to the browser. Once Figwheel starts up, you should be able to open http://localhost:9500 for the development server.

Testing

Either run:

lein fig:test

For a headless test environment using chrome, make sure its installed on your system.

You can also start the dev build and navigate to http://localhost:9500/figwheel-extra-main/auto-testing to get a nice interface while coding that runs the tests on each save.

License

Copyright © 2021 Daniel Berg

Distributed under the Eclipse Public License, the same as Clojure.

Can you improve this documentation? These fine people already did:
Daniel Berg & Yoan Tournade
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close