React Utils

PreviousNext

API reference for @udecode/react-utils.

@udecode/react-utils provides small React primitives used across Plate UI packages. It is also re-exported from platejs/react and @udecode/cn.

Installation

pnpm add @udecode/react-utils
pnpm add @udecode/react-utils

Use direct imports in shared UI packages. Use platejs/react when you are already inside a Plate app surface.

Components

ComponentRendersNotes
PortalBodyReactDOM.createPortal(children, element ?? document.body)Returns children directly when no DOM container is available.
BoxSlot-aware divCreated with createSlotComponent('div'). Supports as and asChild.
TextSlot-aware spanCreated with createSlotComponent('span'). Supports as and asChild.
MemoizedChildrenReact.memo(({ children }) => <>{children}</>)Prevents child-only rerenders when parent props are stable.
Portal to body
import { PortalBody } from '@udecode/react-utils';
 
export function BodyOverlay() {
  return (
    <PortalBody>
      <div role="status">Saving</div>
    </PortalBody>
  );
}
Portal to body
import { PortalBody } from '@udecode/react-utils';
 
export function BodyOverlay() {
  return (
    <PortalBody>
      <div role="status">Saving</div>
    </PortalBody>
  );
}

Primitive Factories

Use primitive factories when a component needs asChild, composed refs, hook-provided props, or hook-provided state.

Parameters

    Default element or component.

ReturnsReact.ForwardRefExoticComponent

    A component that renders Slot when asChild is true, as when provided, otherwise the default element.

Parameters

    HTML tag to render.

ReturnsReact.ForwardRefExoticComponent

    A typed forwardRef component for that intrinsic element.

Parameters

    Default element or component.

    Hook used to create state when the caller does not provide state.

    Hook used to derive props, hidden state, and a ref from state.

ReturnsReact.ForwardRefExoticComponent

    A primitive component with as, asChild, options, state, className, style, and setProps.

createPrimitiveComponent merges hook class names before consumer class names, merges hook style before consumer style, composes forwarded refs with hook refs, and returns null when hidden is true unless asChild is set.

Ref and Effect Hooks

APITypeBehavior
composeRefs(...refs)(...refs) => (node) => cleanup?Sets callback refs and ref objects to the same node. If refs return cleanup functions, the composed ref returns a cleanup.
useComposedRef(...refs)(...refs) => refCallbackMemoized composeRefs callback.
useStableFn(fn, deps?)(fn, deps = []) => stableFnReturns a stable function that calls the latest fn.
useStableMemo(producer, deps?)(producer, deps?) => valueStores a produced value in state and updates it in a layout effect.
useEffectOnce(effect, deps)(effect, deps) => voidRuns the effect on first render and again when the dependency values change.
useIsomorphicLayoutEffectReact.useLayoutEffect | React.useEffectUses layout effect in the browser and effect during SSR.
Compose refs
import * as React from 'react';
import { useComposedRef } from '@udecode/react-utils';
 
export const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<'input'>>(
  (props, ref) => {
    const localRef = React.useRef<HTMLInputElement>(null);
    const composedRef = useComposedRef(ref, localRef);
 
    return <input ref={composedRef} {...props} />;
  }
);
Compose refs
import * as React from 'react';
import { useComposedRef } from '@udecode/react-utils';
 
export const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<'input'>>(
  (props, ref) => {
    const localRef = React.useRef<HTMLInputElement>(null);
    const composedRef = useComposedRef(ref, localRef);
 
    return <input ref={composedRef} {...props} />;
  }
);

Outside Click

useOnClickOutside returns a callback ref unless you pass explicit refs.

Parameters

    Called when a configured event lands outside every tracked element.

    Removes listeners while true.

    Defaults to ['mousedown', 'touchstart'].

    Defaults to ignore-onclickoutside. Matching ancestors are ignored.

    Ignores scrollbar clicks.

    Defaults to true. Uses window blur to detect iframe focus.

    Explicit refs to observe instead of the returned callback ref.

Returns(element: HTMLElement | null) => void

    Callback ref that registers an element for outside-click detection.

Memo and Event Helpers

APITypeBehavior
useMemoizedSelector(selector, deps, equalityFn?)(selector, deps, equalityFn?) => valueRe-renders only when the selector result changes. The default equality is strict equality.
composeEventHandlers(original, next, options?)(event) => voidCalls original, then calls next unless event.defaultPrevented and checkForDefaultPrevented is true.

Component Wrappers

Parameters

    Forward-ref render function.

ReturnsReact.ForwardRefExoticComponent

    Typed React.forwardRef result.

Parameters

    Providers to wrap around the component. Array entries pass props to a provider.

    Component to wrap.

Returns(props: T) => React.ReactElement

    Component wrapped by the providers from right to left.

Wrap providers
import { withProviders } from '@udecode/react-utils';
 
const ThemeProvider = ({ children }: { children: React.ReactNode }) => (
  <div data-theme="dark">{children}</div>
);
 
const Page = () => <main>Docs</main>;
 
export const ThemedPage = withProviders(ThemeProvider)(Page);
Wrap providers
import { withProviders } from '@udecode/react-utils';
 
const ThemeProvider = ({ children }: { children: React.ReactNode }) => (
  <div data-theme="dark">{children}</div>
);
 
const Page = () => <main>Docs</main>;
 
export const ThemedPage = withProviders(ThemeProvider)(Page);

Related APIs

  • cn covers @udecode/cn, which re-exports this package.
  • Plate covers the platejs/react umbrella export.