com.fulcrologic.fulcro.react.hooks — com.fulcrologic/fulcro 3.7.6

React hooks wrappers and helpers. The wrappers are simple API simplifications that help when using hooks from Clojurescript, but this namespace also includes utilities for using Fulcro's data/network management from raw React via hooks.

See use-root, use-component, and use-uism.

use-callback clj/s

(use-callback cb)

(use-callback cb args)

A simple wrapper around React/useCallback. Converts args to js array before send.

React docs: https://reactjs.org/docs/hooks-reference.html#usecallback

use-component clj/s

(use-component app
               component
               {:keys [initialize? initial-params keep-existing?]
                :or {initial-params {}}
                :as options})

Use Fulcro from raw React. This is a Hook effect/state combo that will connect you to the transaction/network/data processing of Fulcro, but will not rely on Fulcro's render. Thus, you can embed the use of the returned props in any stock React context. Technically, you do not have to use Fulcro components for rendering, but they are necessary to define the query/ident/initial-state for startup and normalization. You may also use this within normal (Fulcro) components to generate dynamic components on-the-fly (see nc).

The arguments are:

app - A Fulcro app component - A component with query/ident. Queries MUST have co-located normalization info. You can create this with normal defsc or as an anonymous component via raw.components/nc. options - A map of options, containing:

• :initial-params - The parameters to use when getting the initial state of the component. See comp/get-initial-state. If no initial state exists on the top-level component, then an empty map will be used. This will mean your props will be empty to start.
• initialize? - A boolean (default true). If true then the initial state of the component will be used to pre-populate the component's state in the app database.
• :keep-existing? - A boolean. If true, then the state of the component will not be initialized if there is already data at the component's ident (which will be computed using the initial state params provided, if necessary).
• :ident - Only needed if you are NOT initializing state, AND the component has a dynamic ident.

Returns the props from the Fulcro database. The component using this function will automatically refresh after Fulcro transactions run (Fulcro is not a watched-atom system. Updates happen at transaction boundaries).

MAY return nil if no data is at that component's ident.

See also use-root.

use-context clj/s

(use-context ctx)

A simple wrapper around the RAW React/useContext. You should probably prefer the context support from c.f.f.r.context.

use-debug-value clj/s

(use-debug-value value)

(use-debug-value value formatter)

A simple wrapper around React/useDebugValue.

React docs: https://reactjs.org/docs/hooks-reference.html#uselayouteffect

use-deferred-value clj/s

(use-deferred-value value)

A simple wrapper around React/useDeferredValue.

React docs: https://reactjs.org/docs/hooks-reference.html#usedeferredvalue

use-effect clj/s macro

(use-effect f)

(use-effect f dependencies)

A simple macro wrapper around React/useEffect that does compile-time conversion of dependencies to a js-array for convenience without affecting performance.

React docs: https://reactjs.org/docs/hooks-reference.html#useeffect

use-fulcro-mount clj/s

(use-fulcro-mount parent-this {:keys [child-class initial-state-params]})

NOTE: In many cases you are better off using the other hooks support in this ns, such as use-component, since they do not have a render integration requirement.

Generate a new sub-root that is controlled and rendered by Fulcro's multi-root-renderer.

;; important, you must use hooks (`defhc` or `:use-hooks? true`)
(defsc NewRoot [this props]
  {:use-hooks? true}
  (let [f (use-fulcro-mount this {:child-class SomeChild})]
    ;; parent props will show up in SomeChild as computed props.
    (f props)))

WARNING: Requires you use multi-root-renderer.

use-gc clj/s

(use-gc this-or-app ident edges)

Effect handler. Creates an effect that will garbage-collect the given ident from fulcro app state on cleanup, and will follow any edges (a set of keywords) and remove any things pointed through those keywords as well. See normalized-state's remove-entity.

(defsc NewRoot [this props]
  {:use-hooks? true}
  (let [generated-id (hooks/use-generated-id)
        f (use-fulcro-mount this {:child-class SomeChild
                                  :initial-state-params {:id generated-id})]
    ;; will garbage-collect the floating root child on unmount
    (use-gc this [:child/id generated-id] #{})
    (f props)))

use-generated-id clj/s

(use-generated-id)

Returns a constant ident with a generated ID component.

use-id clj/s

(use-id)

A simple wrapper around React/useId. See also use-generated-id, which is a Fulcro-specific function for generating random uuids.

React docs: https://reactjs.org/docs/hooks-reference.html#useid

use-imperative-handle clj/s

(use-imperative-handle ref f)

A simple wrapper around React/useImperativeHandle.

React docs: https://reactjs.org/docs/hooks-reference.html#useimperativehandle

use-insertion-effect clj/s

(use-insertion-effect didUpdate)

A simple wrapper around React/useInsertionEffect.

React docs: https://reactjs.org/docs/hooks-reference.html#useinsertioneffect

use-layout-effect clj/s

(use-layout-effect f)

(use-layout-effect f args)

A simple wrapper around React/useLayoutEffect.

React docs: https://reactjs.org/docs/hooks-reference.html#uselayouteffect

use-lifecycle clj/s macro

(use-lifecycle setup)

(use-lifecycle setup teardown)

A macro shorthand that evaluates to low-level js at compile time for (use-effect (fn [] (when setup (setup)) (when teardown teardown)) [])

use-memo clj/s

(use-memo value-factory-fn)

(use-memo value-factory-fn dependencies)

A simple wrapper around React/useMemo. Converts args to js array before send.

NOTE: React does NOT guarantee it won't re-create the value during the lifetime of the component, so it is sorta crappy in terms of actual memoization. Purely for optimizations, not for guarantees.

React docs: https://reactjs.org/docs/hooks-reference.html#usememo

use-reducer clj/s

(use-reducer reducer initial-arg)

(use-reducer reducer initial-arg init)

A simple wrapper around React/useReducer. Returns a cljs vector for easy destructuring

React docs: https://reactjs.org/docs/hooks-reference.html#usecontext

use-ref clj/s

(use-ref)

(use-ref value)

A simple wrapper around React/useRef.

React docs: https://reactjs.org/docs/hooks-reference.html#useref

use-root clj/s

(use-root app
          root-key
          component
          {:keys [initialize? keep-existing? initial-params] :as options})

Use a root key and component as a subtree managed by Fulcro from raw React. The root-key must be a unique (namespace recommended) key among all keys used within the application, since the root of the database is where it will live.

The component should be a real Fulcro component or a generated normalizing component from nc (or similar).

Returns the props (not including root-key) that satisfy the query of component. MAY return nil if no data is available.

See also use-component.

use-state clj/s

(use-state initial-value)

A simple wrapper around React/useState. Returns a cljs vector for easy destructuring.

initial-value can be a function.

React docs: https://reactjs.org/docs/hooks-reference.html#usestate

use-sync-external-store clj/s

(use-sync-external-store subscribe get-snapshot)

(use-sync-external-store subscribe get-snapshot get-server-ss)

A simple wrapper around React/useSyncExternalStore.

React docs: https://reactjs.org/docs/hooks-reference.html#usesyncexternalstore

use-transition clj/s

(use-transition value)

A simple wrapper around React/useTransition.

React docs: https://reactjs.org/docs/hooks-reference.html#usetransition

use-uism clj/s

(use-uism app state-machine-definition id options)

Use a UISM as an effect hook. This will set up the given state machine under the given ID, and start it (if not already started). Your initial state handler MUST set up actors and otherwise initialize based on options.

If the machine is already started at the given ID then this effect will send it an :event/remounted event.

You MUST include :componentName in each of your actor's normalizing component options (e.g. (nc query {:componentName ::uniqueName})) because UISM requires component appear in the component registry (components cannot be safely stored in app state, just their names).

options is a map that can contain ::uism/actors as an actor definition map (see begin!). Any other keys in options are sent as the initial event data when the machine is started.

Returns a map that contains the actor props (by actor name) and the current state of the state machine as :active-state.

useEffect clj/s

(useEffect f)

(useEffect f js-deps)

A CLJC wrapper around js/React.useEffect that does NO conversion of dependencies. You probably want the macro use-effect instead.

React docs: https://reactjs.org/docs/hooks-reference.html#useeffect

useState clj/s

(useState initial-value)

A simple CLJC wrapper around React/useState. Returns a JS vector for speed. You probably want use-state, which is more convenient.

React docs: https://reactjs.org/docs/hooks-reference.html#usestate