reagent.core

Components, Reagent atoms, cursors, reactions and React interop.

adapt-react-classfunction

(adapt-react-class c)

Returns an adapter for a native React class, that may be used just like a Reagent component function or class in Hiccup forms.

Source

after-renderfunction

(after-render f)

Run f using requestAnimationFrame or equivalent.

f will be called just after any queued renders in the next animation frame (and even if no renders actually occur).

Source

argvfunction

(argv this)

Returns the entire Hiccup form passed to the component.

Source

as-elementfunction

(as-element form)
(as-element form compiler)

Turns a vector of Hiccup syntax into a React element. Returns form unchanged if it is not a vector.

Source

atomfunction

(atom x)
(atom x & rest)

Like clojure.core/atom, except that it keeps track of derefs. Reagent components that derefs one of these are automatically re-rendered.

Source

childrenfunction

(children this)

Returns the children passed to a component.

Source

class-namesfunction

(class-names)
(class-names class)
(class-names class1 class2)
(class-names class1 class2 & others)

Function which normalizes and combines class values to a string

Reagent allows classes to be defined as:

  • Strings
  • Named objects (Symbols or Keywords)
  • Collections of previous types, including nested collections
  • nil values, which are ignored
(class-names :a ["b" nil [:c [:d]]])
;; => "a b c d"
Source

create-classfunction

(create-class spec)
(create-class spec compiler)

Creates JS class based on provided Clojure map, for example:

{;; Constructor
 :constructor (fn [this props])
 :get-initial-state (fn [this])
 ;; Static methods
 :get-derived-state-from-props (fn [props state] partial-state)
 :get-derived-state-from-error (fn [error] partial-state)
 ;; Methods
 :get-snapshot-before-update (fn [this old-argv new-argv] snapshot)
 :should-component-update (fn [this old-argv new-argv])
 :component-did-mount (fn [this])
 :component-did-update (fn [this old-argv old-state snapshot])
 :component-will-unmount (fn [this])
 :component-did-catch (fn [this error info])
 :reagent-render (fn [args....])
 ;; Or alternatively:
 :render (fn [this])
 ;; Deprecated methods:
 :UNSAFE_component-will-receive-props (fn [this new-argv])
 :UNSAFE_component-will-update (fn [this new-argv new-state])
 :UNSAFE_component-will-mount (fn [this])}

Everything is optional, except either :reagent-render or :render.

Map keys should use React.Component method names (https://reactjs.org/docs/react-component.html), and can be provided in kebab-case or camelCase.

State can be initialized using constructor, which matches React.Component class, or using getInitialState which matches old React createClass function and is now implemented by Reagent for compatibility.

State can usually be anything, e.g. Cljs object. But if using getDerivedState methods, the state has to be plain JS object as React implementation uses Object.assign to merge partial state into the current state.

React built-in static methods or properties are automatically defined as statics.

Source

create-compilerfunction

(create-compiler opts)

Creates Compiler object with given opts, this can be passed to render, as-element and other functions to control how they turn the Reagent-style Hiccup into React components and elements.

Source

create-elementfunction

(create-element type)
(create-element type props)
(create-element type props child)
(create-element type props child & children)

Create a native React element, by calling React.createElement directly.

That means the second argument must be a javascript object (or nil), and that any Reagent hiccup forms must be processed with as-element. For example like this:

(r/create-element "div" #js{:className "foo"}
  "Hi " (r/as-element [:strong "world!"])

which is equivalent to

[:div.foo "Hi" [:strong "world!"]]
Source

current-componentfunction

(current-component)

Returns the current React component (a.k.a this) in a component function.

Source

cursorfunction

(cursor src path)

Provide a cursor into a Reagent atom.

Behaves like a Reagent atom but focuses updates and derefs to the specified path within the wrapped Reagent atom. e.g.,

(let [c (cursor ra [:nested :content])]
  ... @c ;; equivalent to (get-in @ra [:nested :content])
  ... (reset! c 42) ;; equivalent to (swap! ra assoc-in [:nested :content] 42)
  ... (swap! c inc) ;; equivalence to (swap! ra update-in [:nested :content] inc)
  )

The first parameter can also be a function, that should look something like this:

(defn set-get
  ([k] (get-in @state k))
  ([k v] (swap! state assoc-in k v)))

The function will be called with one argument – the path passed to cursor – when the cursor is deref'ed, and two arguments (path and new value) when the cursor is modified.

Given that set-get function, (and that state is a Reagent atom, or another cursor) these cursors are equivalent: (cursor state [:foo]) and (cursor set-get [:foo]).

Note that a cursor is lazy: it doesn't watch the source atom by itself, so its value is only updated when the cursor is deref'ed or changed through the cursor (reset!/swap!). Watches added with add-watch on a cursor are therefore not called when the source atom is changed directly, unless the cursor is deref'ed in a reactive context (a component render, track!, run!, a reaction), in which case they are called when queued updates are processed (next animation frame, or flush). Intermediate values may be skipped. A cursor that watched its source eagerly would have to be disposed to avoid leaking.

To react to changes of the source atom outside components, either add-watch the source atom and compare the value at the path, or use (track! (fn [] (do-something @c))) and dispose! it when done.

Source

defcmacro

(defc name doc-string? attr-map? [params*] prepost-map? body)
(defc name doc-string? attr-map? ([params*] prepost-map? body) + attr-map?)

Create a Reagent function component

The functions works like other components (defined using regular defn) when used inside hiccup elements ([component]), but it can't be used like a regular function. The created function is a React JS function component, i.e., it takes single js-props argument, and the function body is already wrapped to use Reagent implementation to work with Ratoms etc.

Source

dispose!function

(dispose! x)

Stop the result of track! from updating.

Source

flushfunction

(flush)

Render dirty components immediately.

Note that this may not work in event handlers, since React.js does batching of updates there.

Source

force-updatefunction

(force-update this)

Force a component to re-render immediately.

If the second argument is true, child components will also be re-rendered, even if their arguments have not changed.

Source

is-clientvar

No docstring.

Source

merge-propsfunction

(merge-props)
(merge-props defaults)
(merge-props defaults props)
(merge-props defaults props & others)

Utility function that merges some maps, handling :class and :style.

The :class value is always normalized (using class-names) even if no merging is done.

Source

next-tickfunction

(next-tick f)

Run f using requestAnimationFrame or equivalent.

f will be called just before components are rendered.

Source

partialfunction

(partial f & args)

Works just like clojure.core/partial, but the result can be compared with =

Source

propsfunction

(props this)

Returns the props passed to a component.

Source

reactify-componentfunction

(reactify-component c)
(reactify-component c compiler)

Returns an adapter for a Reagent component, that may be used from React, for example in JSX. A single argument, props, is passed to the component, converted to a map.

With a compiler using {:function-components true} option, returns a React function component, so the Reagent component can use React hooks. Otherwise returns a class component.

The result is a React component: to use it in Hiccup, use :> like with other React components, or use the original Reagent component directly.

Source

reactionmacro

(reaction & body)

Creates Reaction from the body, returns a derefable containing the result of the body. If the body derefs reactive values (Reagent atoms, track, etc), the body will run again and the value of the Reaction is updated.

New Reaction is created everytime reaction is called, so caller needs to take care that new reaction isn't created e.g. every component render, by using with-let, form-2 or form-3 components or other solutions. Consider using reagent.core/track, for function that caches the derefable value, and can thus be safely used in e.g. render function safely.

Source

renderfunctiondeprecated

(render & _)

No docstring.

Source

replace-statefunction

(replace-state this new-state)

Set state of a component. Equivalent to (reset! (state-atom this) new-state)

Source

rswap!function

(rswap! a f & args)

Swaps the value of a to be (apply f current-value-of-atom args).

rswap! works like swap!, except that recursive calls to rswap! on the same atom are allowed – and it always returns nil.

Source

set-default-compiler!function

(set-default-compiler! compiler)

Globally sets the Compiler object used by render, as-element and other calls by default, when no compiler parameter is provided.

Use nil value to restore the original default compiler.

Source

set-statefunction

(set-state this new-state)

Merge component state with new-state. Equivalent to (swap! (state-atom this) merge new-state)

Source

statefunction

(state this)

Returns the state of a component, as set with replace-state or set-state. Equivalent to (deref (r/state-atom this))

Source

state-atomfunction

(state-atom this)

Returns an atom containing a components state.

Source

trackfunction

(track f & args)

Takes a function and optional arguments, and returns a derefable containing the output of that function. If the function derefs Reagent atoms (or track, etc), the value will be updated whenever the atom changes.

In other words, @(track foo bar) will produce the same result as (foo bar), but foo will only be called again when the atoms it depends on changes, and will only trigger updates of components when its result changes.

track is lazy, i.e the function is only evaluated on deref.

Source

track!function

(track! f & args)

An eager version of track. The function passed is called immediately, and continues to be called when needed, until stopped with dispose!.

Source

unsafe-htmlfunction

(unsafe-html s)

Create a tagged value for use with :dangerouslySetInnerHTML. Reagent doesn't allow other values to be used with the property, to ensure data from external sources (using EDN or Transit) can't be used to accidentally create arbitrary HTML.

See doc/Security.md

Source

with-letmacro

(with-let bindings & body)

Bind variables as with let, except that when used in a component the bindings are only evaluated once. Also takes an optional finally clause at the end, that is executed when the component is destroyed.

Source

wrapfunction

(wrap value reset-fn & args)

Provide a combination of value and callback, that looks like an atom.

The first argument can be any value, that will be returned when the result is deref'ed.

The second argument should be a function, that is called with the optional extra arguments provided to wrap, and the new value of the resulting 'atom'.

Use for example like this:

(wrap (:foo @state)
      swap! state assoc :foo)

Probably useful only for passing to child components.

Source