Need help with fork?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

189 Stars 9 Forks MIT License 135 Commits 1 Opened issues


A non-intrusive Clojurescript form management library for Re-frame and Reagent.

Services available


Need anything else?

Contributors list

# 256,099
131 commits
# 151,917
Visual ...
1 commit


Yet another Form Library to add to the list. Inspired by Formik.

For Reagent & Re-frame


Clojars Project

Why Fork?

Forms are hard. Orchestrating their ever changing state, complex logic, and rich UI elements is quite a challenging task.

Fork tries to establish a pattern by abstracting away the bits of code that can be generalized to shift the developer's focus on the features implementation. The following points represent the pillars Fork was built upon:

  • Control - You code your form components
  • Adaptable - Plug it in and take only what you need
  • Separation of concerns - Logic and UI live in different places
  • CSS Free - You manage the style

It's worth to point out that from v2.0.0 this library doesn't necessarily require re-frame. In fact, you can use it exclusively with Reagent.

As at this state you must be dying of curiosity, I will dive right into the implementation details, hoping that this will help you save the day... and some nerves.


Require Fork

In Deps

fork {:mvn/version "2.4.2"}


fork {:git/url ""
      :sha "sha commit"}

In Namespace

(ns your.namespace
    ;; depending on what you want to use
    [ :as fork]
    [fork.reagent :as fork-reagent]))

Note that the APIs of
are identical, so I will be using only the former in the following examples.

The Bare Minimum

(defn my-form
  [{:keys [values handle-change handle-blur]}]
   [:p "Read back: " (values "input")]
    {:name "input"
     :value (values "input")
     :on-change handle-change
     :on-blur handle-blur}]])

(defn foo [] [fork/form {:initial-values {"input" "hello"}} my-form])

Notice that Fork takes only two parameters. The first one is a map of config, and the second one is a function that returns your form component. Many API helpers are accessible as first argument of the form function that wraps your form component.

Starting from the config map,

might be provided to make Fork aware of any of your prefilled form values. Make sure to match the
of your inputs with what you define in the
map to successfully link up the two. You may want to use keywords for input names. If you do, remember to set the option
to true. If you don't need to set default values for your fields, you can simply discard the key.

Can I go anonymous?

You can also return your component in an anonymous function, but you have to be careful not to cause unwanted re-renderings by updating any external state. The following code is an example of what you want to avoid, when using an anonymous function:

;;!!!!! BAD CODE !!!!!

(defn foo [] (let [external-input (r/atom nil)] (fn [] [:div [:input {:value @external-input :on-change #(reset! external-input (-> % .-target .-value))}] [fork/form {} (fn [{:keys [values form-id handle-change handle-blur] :as props}] [:form {:id form-id} [:input {:name "name" :value (values "name") :on-change #(do (reset! external-input "some-value") (handle-change %)) :on-blur handle-blur}]])]])))

;;!!!!! BAD CODE !!!!!

Briefly, the

input will lose focus every time its
event is dispatched. This happens because the handler creates a new value for the
state, which sparks the re-rendering of the whole

As a solution, you might keep the anonymous function in place as long as you remember to use the

component exclusively for the logic related to

How do I submit a form?

(ns your.namespace
   [ :as fork]
   [re-frame.core :as rf]))

(rf/reg-event-fx :submit-handler (fn [{db :db} [_ {:keys [values dirty path]}]] ;; dirty tells you whether the values have been touched before submitting. ;; Its possible values are nil or a map of changed values {:db (fork/set-submitting db path true) :dispatch-later [{:ms 1000 :dispatch [:resolved-form path values]}]}))

(rf/reg-event-fx :resolved-form (fn [{db :db} [_ path values]] (js/alert values) {:db (fork/set-submitting db path false)}))

(defn foo [] [fork/form {:path [:form] :form-id "form-id" :prevent-default? true :clean-on-unmount? true :on-submit #(rf/dispatch [:submit-handler %])} (fn [{:keys [values form-id handle-change handle-blur submitting? handle-submit]}] [:form {:id form-id :on-submit handle-submit} [:input {:name "input" :value (values "input") :on-change handle-change :on-blur handle-blur}] [:button {:type "submit" :disabled submitting?} "Submit Form"]])])

Let's examine what has been added step by step:

  • Require Re-frame in your namespace
  • Create a Re-frame effect that will be called upon submitting
  • Pass the newly created effect to Fork along with
    and other options
  • Destructure
    to be used in your UI
  • Wrap your inputs in a form tag and add a submit button

If some parts look a bit obscure, the will be explained thoroughly in the following paragraphs.


makes fork aware of your form elements. If it is not specified, a random id will be generated and will be provided through the same
key. - Key

lets you pass a ratom that will be used as a db. Useful if you need to access it outside the fork component. - Ratom

lets you choose where to store your form global events i.e. server related stuff. - Keyword/String OR Vector of keys

allows you to work with keywords instead of strings. - Boolean

does not automatically send your form to the server on submit. - Boolean

resets the state when your component is unmounted. (Useful when used with re-frame). - Boolean

to pass a validation function that gives you the form values in a map as single param. - Function

to pre-populate the inputs. - Map

to pre-populate the inputs and set them as touched. - Map

lets you write your own submit logic. It gives you a map with
:state :path :values :dirty :reset
keys. - Function

to perform any logic after the component is mounted. It takes a function and provides one argument that consists of a map of handlers:
set-touched, set-untouched, set-values, disable, enable, disabled?, handle-change, handle-blur, send-server-request
- Function

The Flow

After clicking the submit button, your

function is invoked. Remember to set submitting? to
with the handler
. After your eventual ajax call, do not forget to set the submitting? value back to false with the same handler to handle the form life cycle.

You probably want to know more than the same old Hello World demonstration. Hence, I have prepared a better example that includes a server request and shows better what Fork can do for you.

(ns your.namespace
   [ajax.core :as ajax]
   [ :as fork]
   [re-frame.core :as rf]))

(rf/reg-event-fx :success (fn [{db :db} [_ result path]] {:db (-> db (assoc :result result) (fork/set-submitting path false) (fork/set-server-message path "Registration successful!"))}))

(rf/reg-event-fx :failure (fn [{db :db} [_ result path]] {:db (-> db (fork/set-submitting path false) (fork/set-server-message path "Registration failed!"))}))

(rf/reg-event-fx :submit-handler (fn [{db :db} [_ {:keys [values path]}]] {:db (fork/set-submitting db path true) :http-xhrio {:method :post :uri "/submit-form" :params values :timeout 2000 :format (ajax/transit-request-format) :response-format (ajax/transit-response-format) :on-success [:success path] :on-failure [:failure path]}}))

(defn foo [] [fork/form {:form-id "id" :path [:form] :prevent-default? true :clean-on-unmount? true :on-submit #(rf/dispatch [:submit-handler %])} (fn [{:keys [values form-id handle-change handle-blur submitting? on-submit-server-message handle-submit]}] [:form {:id form-id :on-submit handle-submit} [:input {:name "input" :value (values "input") :on-change handle-change :on-blur handle-blur}] [:button {:type "submit" :disabled submitting?} "Submit Form"] [:p on-submit-server-message]])])

Cool, but what about validation?

Simply plug in any library of your choice that is side effect free, or build your custom validation.

More details

All you have to do is to pass a function that takes

as only parameter. The returned data will be accessible via the key
, which can be destructured from the props.

Let's now build some real validation for our Fork component using for example the Vlad library:

(def validation
  (vlad/join (vlad/attr ["name"]
                         (vlad/length-in 3 15)))
             (vlad/attr ["password"]
                         (vlad/length-over 7)))))

Connect the wires

Let's integrate the validation with our Fork component to actually display the errors:

[fork/form {:path [:form]
            :form-id "id"
            :validation #(vlad/field-errors validation %)
            :prevent-default? true
            :clean-on-unmount? true
            :on-submit #(rf/dispatch [:submit-handler %])}
 (fn [{:keys [values
    {:id form-id
     :on-submit handle-submit}
     {:name "name"
      :value (values "name")
      :on-change handle-change
      :on-blur handle-blur}]
    (when (touched "name")
      [:div (first (get errors (list "name")))])
     {:name "password"
      :value (values "password")
      :on-change handle-change
      :on-blur handle-blur}]
    (when (touched "password")
      [:div (first (get errors (list "password")))])
     {:type "submit"
      :disabled submitting?}
     "Submit Form"]])]

Noticed anything new? We are simply passing the vlad validation function along with a

key and destructuring
. The latter comes in handy to improve the user experience in that the errors are not shown until the first
event is fired.

When a validation function is provided, the submit button will do nothing until all errors are cleared. The only variable that does change is

, which is incremented every time the submission is attempted. Contrairily,
gets updated only when the developer provided on-submit function is invoked.

Little Vlad note:

To perform

validation I recommend using the helper
, as this really simplifies your logic. Briefly, you can define your validation like the following snippet:
(def form-validation
  (fn [password]
     (vlad/attr ["password"]
                (vlad/chain (vlad/present)
                            (vlad/join (vlad/length-in 6 128))))
     (vlad/attr ["confirm-password"]
                  {:message "Confirm Password must be same as password"}))))))

and pass the password value when giving the function to Fork i.e.

[fork/form {:validation
              ;; passing password to the function
              (form-validation (get % "password"))

Keywords as input names

By passing the option

{:keywordize-keys true}
to Fork, the values and all other state keys will be treated as keywords instead of strings. To make sure the input names are properly registered, use the function
available in the props, when giving the name to the input components i.e.
{:name (normalize-name :bar/foo)}
. Namespaced keys are also supported. If
is used when
is not set, the function will simply return the same value.

Dealing with server requests

Since version

, the handler
provides a way of performing server side validation in callbacks like
, or any other operation that involves your backend code. Here is an example of how it works:
 (fn [_ [_ props]]
   ;; faking a server request
   {:dispatch-later [{:ms 2000 :dispatch [:response props]}]}))

(rf/reg-event-fx :response (fn [{db :db} [_ {:keys [state path values dirty errors touched]}]] ;; only dispatch http request when client side errors are clear (when (empty? (get errors "email")) {:db ;; assuming [email protected] is already taken (if (not= "[email protected]" (get values "email")) (fork/set-waiting db path "email" false) (-> db (fork/set-error path "email" "Email Already Exists") (fork/set-waiting path "email" false)))})))

(defn foo [] [fork/form {:path :form ;; or [:path :to :form] :prevent-default? true :validation #(cond-> {} (empty? (get % "email")) (assoc "email" "Email can't be empty")) :on-submit #(js/alert %)} (fn [{:keys [form-id values server-errors handle-change handle-blur handle-submit send-server-request]}] [:div [:form {:id form-id :on-submit handle-submit} [:input {:name "email" :value (values "email") :on-blur handle-blur :on-change (fn [evt] (handle-change evt) (send-server-request {:name "email" ;; this retrieves the most up to date value :value (fork/retrieve-event-value evt) ;; defaults to true :set-waiting? true ;; to clean up relevant state before each http request :clean-on-refetch ["email"] :debounce 500} #(rf/dispatch [:server-request %])))}] [:div (or (get errors "email") (get server-errors "email"))] [:button {:type "submit"} "Submit"]]])])

After destructuring

, this function is invoked within the
handler. It takes two parameters being:
  • A config map with the following keys
{;; REQUIRED - as it's used as a state holder internally
 :name "email"
 ;; OPTIONAL - if not provided the callback will receive the old value
 :value (fork/retrieve-event-value evt)
 ;; OPTIONAL - relevant in the :on-blur case as it sets the `touched` property
 :evt :on-change
 ;; OPTIONAL - to stop the form from submitting while the server request is being processed
 :set-waiting? true
 ;; OPTIONAL - gets rid of any metadata about the provided keys at each server request
 :clean-on-refetch ["email"]
 :throttle 500
 :debounce 500}
  • A function that performs the server request, which will be invoked with the following map keys as args
    :state :path :values :touched :errors :dirty

To prevent the form submission while waiting for a server response, a

:waiting? true
key value pair is stored in the state and needs to be set to false after the server logic is resolved. You can do this yourself or use
(fork/set-waiting db path "email" false)
, as shown above. Now, the form can be submitted.

Global accessible helpers

There are several global helpers:

, and

Note that they do not include side effects at their core. Contrarily, they are meant to simply operate on the old state in order to return the updated one.

When used with re-frame, these handlers can be safely called on the

of your events. In a purely reagent context, they can be provided as arguments of the
function i.e.
(swap! state f/set-submitting path true)

The reason behind their side effect free design is to make them composable, thus preventing the triggering of multiple state updates. In practice, this approach favors this:

(swap! state #(-> %
                  (f/set-submitting path true)
                  (update :some-key inc)))

Instead of the inefficient version:

(swap! state f/set-submitting path true)
(swap! state update :some-key inc)

Field Array

The field array becomes useful when the user might provide zero, one, or many entries for a specific form component. For instance, let's assume we want to collect the user siblings' name. Clearly, there is no way of knowing in advance how many siblings the user has, so we can provide a field array to solve the issue.

(defn field-array-fn
   {:fieldarray/keys [fields
    (fn [idx field]
      ^{:key idx}
        [:label "First Name"]
         {:name "first-name"
          :value (get field "first-name")
          :on-change #(handle-change % idx)
          :on-blur #(handle-blur % idx)}]]
        [:label "Last Name"]
         {:name "last-name"
          :value (get field "last-name")
          :on-change #(handle-change % idx)
          :on-blur #(handle-blur % idx)}]]
        {:type "button"
         :on-click #(when (> (count fields) 1) (remove idx))}
        [:span "Remove"]]])
    {:type "button"
     :on-click #(insert {"first-name" "" "last-name" ""})}
    "Add new person"]])

(defn fork-fieldarray [] [fork/form {:on-submit #(js/alert (:values %)) :initial-values {"siblings" [{"first-name" "" "last-name" ""}]} :prevent-default? true} (fn [{:keys [handle-submit] :as props}] [:div [:form {:on-submit handle-submit} [:h2 "Siblings"] [:div [fork/field-array {:props props :name "siblings"} field-array-fn] [:br][:br] [:div [:button "Submit"]]]]])])


must be a different reagent component to avoid the inputs focus loss. A comprehensive example of the fieldarray functionality can be found here.

What follows is a list of the fieldarray available handlers:

:fieldarray/name ;; name chosen for the field array
:fieldarray/options ;; it holds any user custom props they need in the fieldarray component scope
:fieldarray/fields ;; the fieldarray data. It's a vector of maps
:fieldarray/touched ;; (touched idx :my-input)
:fieldarray/insert ;; (insert {:my-field-array-input "hello"})
:fieldarray/remove ;; (remove idx)
:fieldarray/set-handle-change ;; same as the one in main props (see below)
:fieldarray/set-handle-blur ;; same as the one in main props (see below)
:fieldarray/handle-change ;; (handle-change evt idx)
:fieldarray/handle-blur ;; (handle-blur evt idx)}
:fieldarray/current-target-idx ;; returns idx of droppable item location (current-target-idx :field-array-key)
:fieldarray/current-dragged-idx ;; returns idx of dragged item (current-dragged-idx :field-array-key)
:fieldarray/next-droppable-target? ;; true if hovered item is > than dragged (next-droppable-target? :field-array-key idx)
:fieldarray/prev-droppable-target? ;; true if hovered item is < than dragged (prev-droppable-target? :field-array-key idx)
:fieldarray/drag-and-drop-handlers ;; all drag and drop handlers
;; i.e. [:div (merge {:class ...} (drag-and-drop-handlers :field-array-key idx))]

Does Fork do anything else for me?

You bet it does. The keys you can currently access from your form function are:

  [db ;; 

Quick overview

Here is a demonstration on how to use the above handlers that have not been mentioned so far:

;; db is simply the dereferenced re-frame state that fork uses for global logic

;; state is the local ratom used for the full form core logic (swap! state assoc :something :new)

;; to remove full state (reset)

;; to reset state to given map (reset {:values {"name" "John"} :touched #{"name"}})

(set-touched "input" "another-input")

(set-untouched "input" "another-input")

(set-values {"input" "new-value"})

(set-values {"input" "new-value" "another-input" "new-value-too"})

(disable "input")

(disable "input" "another-input")

(enable "input")

(enable "input" "another-input")

;; input component [:input {... :name (normalize-name :foo/bar) :disabled (disabled? "input") ...}]

(set-handle-change {:value "Joe" ;; or (fn [previous-val] "Joe") :path ["name"]})

(set-handle-blur {:value true ;; or false :path ["name"]})

For what concerns the

key, you can use it as a way of passing arguments to the form component. Here is a quick example:
(defn my-form
  [{:keys [props ...]}]
  ;; props accessible in here!

(defn foo [] [fork/form {:props {:arg1 "foo" :arg2 "bar"} ...} my-form])

Do I really need to build all components from the ground up?

Certainly not, Fork gives you some pre-built inputs, yet you are condemning yourself to the Bulma CSS framework if you ever choose to go down that route. Creating your own wrappers would work much better, allowing you to retain full control on the style. Having said that, these are the few components that ship with Fork.

Bulma CDN

The quickest way to get Bulma is to require the CSS in the header of your index.html file:


(ns your.namespace
   [fork.bulma :as bulma]))
[bulma/input props
 {:name "input"
  :label "First Name"
  :placeholder "Joe"
  :type "text"
  :class "your-css-class"}]

To get all the props from your form function in one shot, you can add :as props just like this:

{:keys [values ..] :as props}

Text Area

[bulma/textarea props
 {:name "area"
  :label "Summary"
  :placeholder "Max 400 words"
  :type "text"
  :class "your-css-class"}]


[bulma/checkbox props
 {:name "agree"
  :text "Plain text or component as well"}]

If you pass a component to

such as
[:div "Some text"]
, add the
display: inline;
style to the element.


[bulma/pretty-dropdown props
 {:label "Optional Label"
  :name "pretty-dropdown"
  :options [{"key-1" 1}
            {"key-2" 2}
            {"key-3" 3}]
  :class "Optional Css Class"}]
[bulma/dropdown props
 {:label "Optional Label"
  :name "pretty-dropdown"
  :options [{"key-1" 1}
            {"key-2" 2}
            {"key-3" 3}]
  :class "Optional Css Class"}]

Can I go make my forms now?

Yes you can. This documentation should get you started with Fork the right way so that you can be productive with it. Ideas, comments (good or bad), and suggestions are always welcome!

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.