koolcodez / fork logo
esc

Type to search...

Form Component Props

Your form render function receives a single map with these keys:

Prop Type Default Description
values (name) → value — Function that returns the current value for a given field name.
errors map | nil — Client-side validation errors. Shape depends on your validation function. nil when no validation is configured or no errors exist.
server-errors map | nil — Server-side validation errors set via set-error. nil when no server errors exist.
touched (name) → boolean — Returns truthy when the field has been blurred or when attempted-submissions > 0.
dirty map | nil — Map of values that differ from initial-values. nil when nothing has changed.
form-id string — The form ID (user-provided or auto-generated). Use as the :id on your <form> element.
submitting? boolean — True when set-submitting has been called with true. Use to disable the submit button.
attempted-submissions number — Number of times handle-submit has been called, including blocked attempts.
successful-submissions number — Number of times the :on-submit callback actually fired (passed all validation).
on-submit-server-message string | nil — Message set via set-server-message. Use for post-submission feedback.
state ratom — The raw ratom backing the form. For direct access when you need it.
path vector — The resolved path in re-frame app-db. Always a vector.
db map — Dereferenced re-frame state at :path. Only available in fork.re-frame.
props any — Whatever you passed via the :props config key.

Event Handlers

Prop Type Default Description
handle-change (evt) → nil — Wire to :on-change. Extracts the field name and value from the DOM event and updates the form state.
handle-blur (evt) → nil — Wire to :on-blur. Marks the field as touched so validation errors become visible.
handle-submit (evt) → nil — Wire to :on-submit on the <form> element. Increments attempted-submissions, checks validation and server state, then calls your :on-submit if everything is clear.

Programmatic State Updates

Prop Type Default Description
set-values (map) → nil — Merges the provided map into form values and marks those fields as touched. e.g. (set-values {"name" "John"})
set-touched (& names) → nil — Marks fields as touched. e.g. (set-touched "name" "email")
set-untouched (& names) → nil — Removes fields from the touched set. e.g. (set-untouched "name")
set-handle-change (map | vec) → nil — Programmatic value change. Accepts {:value "x" :path ["field"]} or a vector of such maps. Value can be a function receiving the current value.
set-handle-blur (map) → nil — Programmatic blur. Accepts {:value true/false :path ["field"]}. When true, marks as touched; when false, unmarks.
disable (& names) → nil — Adds fields to the disabled set. e.g. (disable "name" "email")
enable (& names) → nil — Removes fields from the disabled set. e.g. (enable "name")
disabled? (name) → boolean — Returns true if the field is in the disabled set.
normalize-name (keyword) → string — Converts a keyword to a string suitable for DOM name attributes. Only active when :keywordize-keys is true.
reset (& [map]) → nil — Resets the entire form state. Optionally accepts a map to use as the new state. e.g. (reset) or (reset {:values {"name" "John"} :touched #{"name"}})
send-server-request (config, callback) → nil — Triggers a server-side validation request. See Server Requests guide for full config options.

Global Helpers

These functions are side-effect-free. They take state (a db map or ratom contents) and return the updated state. Use them inside swap! (Reagent) or reg-event-db (Re-frame):

Prop Type Default Description
set-submitting (db, path, bool) → db — Sets the submitting flag at the given path. Use true before an async operation, false after.
set-waiting (db, path, input-name, bool) → db — Sets the waiting flag for a specific field. While any field is waiting, form submission is blocked.
set-error (db, path, input-name, message) → db — Injects a server-side error for a specific field. Accessible via :server-errors in the form component.
set-server-message (db, path, message) → db — Sets a global server message (success or failure). Accessible via :on-submit-server-message.
retrieve-event-value (evt) → value — Extracts the value from a DOM event. Handles checkboxes (returns checked boolean) and standard inputs (returns value string).
global-helpers.cljs 
;; Reagent: composable inside swap!
(swap! state #(-> %
                  (fork/set-submitting path false)
                  (fork/set-server-message path "Done!")))

;; Re-frame: composable inside event handlers
(rf/reg-event-db
 :handle-response
 (fn [db [_ path]]
   (-> db
       (fork/set-submitting path false)
       (fork/set-server-message path "Done!"))))

Field Array API

The field array component receives a namespaced map as its second argument:

Prop Type Default Description
:fieldarray/fields vector of maps — The current array data.
:fieldarray/insert (map) → nil — Appends a new entry. e.g. (insert {"name" ""})
:fieldarray/remove (idx) → nil — Removes the entry at index. Touched state shifts correctly.
:fieldarray/handle-change (evt, idx) → nil — Like handle-change but scoped to a specific array index.
:fieldarray/handle-blur (evt, idx) → nil — Like handle-blur but scoped to a specific array index.
:fieldarray/touched (idx, input-key) → boolean — Returns truthy if the field at the given index has been touched.
:fieldarray/name string | keyword — The name of this field array.
:fieldarray/options any — Custom props passed via the :options key on the field-array config.
:fieldarray/drag-and-drop-handlers (key, idx) → map — Returns a map of HTML5 drag event handlers for the given row. Merge into the row's wrapper element.
:fieldarray/current-target-idx (key) → idx | nil — Returns the index of the current drop target during a drag operation.
:fieldarray/current-dragged-idx (key) → idx | nil — Returns the index of the currently dragged item.
:fieldarray/next-droppable-target? (key, idx) → boolean — True if the hovered item is below the dragged item. Use for drop indicator styling.
:fieldarray/prev-droppable-target? (key, idx) → boolean — True if the hovered item is above the dragged item. Use for drop indicator styling.