Optional cursors library for Reagent
Switch branches/tags
Nothing to show
Clone or download
seancorfield Deprecate this standalone library
Recommend that folks use the Reagent core version of cursors instead of this standalone library.
Latest commit eba5797 Feb 2, 2015
Failed to load latest commit information.
src/reagent fix typo and tests Dec 28, 2014
.gitignore Initial commit Nov 6, 2014
LICENSE Initial commit Nov 6, 2014
README.md Deprecate this standalone library Feb 2, 2015
project.clj add additional info in the readme and increase the version for 'cur' Dec 4, 2014



As part of the migration to the new reagent-project organization, an earlier version of this cursors library was folded into Reagent's core. As part of the Reagent 0.5.0 release, that implementation of cursors has been substantially enhanced (both in performance and in generalization) so this standalone cursor library should be considered deprecated.

Note that the argument order in Reagent core is different - atom first, path second - so switching from this library to Reagent core will involve code changes but they are straightforward.


Cursors can be seen as a kind of pointer to a particular part of an atom, which behaves exactly like a normal atom. This means that you use the same functions you would on an atom (reset!, swap!, deref, add-watch, etc) but affect only the part you are interested in.

This enables you to create reusable functions and components by abstracting away complex paths and getter/setter functions.

;; what was...
(swap! my-atom update-in [:some :path :that :might :be :quite :deep] my-fn)

;; ...can now become

(swap! my-cursor my-fn)

;; Notice that the path is no longer hardcoded; it could be a simple
;; atom, or a cursor pointing to the 10th level of a complex nested
;; hashmap.

;; How about associating a value into the nested structure? No
;; problem! Just `reset!` the cursor:

(reset! my-cursor "my-new-value")

;; Now just deref it:


=> "my-new-value"


Add [reagent/reagent-cursor "0.1.2"] to :dependencies in project.clj.

In your Reagent application (:require [reagent.cursor :as rc]).

There are two main functions available to create cursors: cursor and cur.


cursor has two arities.

When given a single argument (a path), it returns a function that can create a cursor when given an atom. Useful to create mutliple cursors with the same path.

(def my-custom-cursor-fn (rc/cursor [:some :arbitrary :path]))

(map my-custom-cursor-fn [atom1 atom2 atom3])

;; this will return a collection of [cursor1 cursor2 cursor3]

When given two arguments, cursor will return a cursor.

(def c1 (rc/cursor [:some :arbitrary :path] atom1))


cur is the little brother of cursor. It will only accept 2 arguments (the atom and a path), but is guaranteed to return a cursor.

Note that the atom argument is placed on the left, allowing you to use a thread-first macro (cursor requires a thread-last macro).

(-> my-atom
	(rc/cur [:some :path]) ;; <---- create the cursor
	(add-watch :my-watch #(println "updated!"))
	(historian/record! :my-state)
    (ls/local-storage :my-state))


Copyright (c) 2014 Sean Corfield

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