@ariakit/react-utils

Important: This package is an internal dependency of Ariakit and does not follow semantic versioning, meaning breaking changes may occur in patch and minor versions. You probably want to use @ariakit/react instead.

Shared React utilities used by Ariakit React packages.

Contents

• Installation
• Usage
• API reference

Installation

npm i @ariakit/react-utils

Usage

Import helpers from the package root:

import { useEvent } from "@ariakit/react-utils";

This package is ESM-only and exposes a single public entrypoint.

API reference

• Hooks
  • useSafeLayoutEffect
  • useInitialValue
  • useLiveRef
  • useEvent
  • useTransactionState
  • useMergeRefs
  • useId
  • useDeferredValue
  • useTagName
  • useAttribute
  • useUpdateEffect
  • useUpdateLayoutEffect
  • useForceUpdate
  • useBooleanEvent
  • useWrapElement
  • usePortalRef
  • useMetadataProps
  • useIsMouseMoving
• General utilities
  • setRef
  • isValidElementWithRef
  • getRefProperty
  • mergeProps
• System utilities
  • forwardRef
  • memo
  • createElement
  • createHook
  • createStoreContext
• Type utilities
  • RenderProp
  • WrapElement
  • Options
  • HTMLProps
  • Props
  • Hook

Hooks

React hooks for refs, events, ids, effects, and element metadata.

useSafeLayoutEffect

const useSafeLayoutEffect: typeof React.useLayoutEffect;

React.useLayoutEffect that fallbacks to React.useEffect on server side.

useInitialValue

function useInitialValue<T>(value: T | (() => T)): T;

Returns a value that never changes even if the argument is updated.

Example:

function Component({ prop }) {
  const initialProp = useInitialValue(prop);
}

useLiveRef

function useLiveRef<T>(value: T): RefObject<T>;

Creates a React.RefObject that is constantly updated with the incoming value.

Example:

function Component({ prop }) {
  const propRef = useLiveRef(prop);
}

useEvent

function useEvent<T extends AnyFunction>(callback?: T): T;

Creates a stable callback function that has access to the latest state and can be used within event handlers and effect callbacks. Throws when used in the render phase.

Example:

function Component(props) {
  const onClick = useEvent(props.onClick);
  React.useEffect(() => {}, [onClick]);
}

useTransactionState

function useTransactionState<T>(
  callback?: ((state: SetStateAction<T | null>) => void) | null,
): readonly [T | null, React.Dispatch<SetStateAction<T | null>>];

Creates a React state that calls a callback function whenever the state changes and rolls back to the previous state on cleanup.

useMergeRefs

function useMergeRefs(
  ...refs: Array<Ref<any> | undefined>
): ((value: unknown) => (() => void) | undefined) | undefined;

Merges React Refs into a single memoized function ref so you can pass it to an element.

Example:

const Component = React.forwardRef((props, ref) => {
  const internalRef = React.useRef();
  return <div {...props} ref={useMergeRefs(internalRef, ref)} />;
});

useId

function useId(defaultId?: string): string | undefined;

Generates a unique ID. Uses React's useId if available.

useDeferredValue

function useDeferredValue<T>(value: T): T;

Uses React's useDeferredValue if available.

useTagName

function useTagName(
  refOrElement?: RefObject<HTMLElement | null> | HTMLElement | null,
  type?: string | ComponentType,
): string | undefined;

Returns the tag name by parsing an element ref.

Example:

function Component(props) {
  const ref = React.useRef();
  const tagName = useTagName(ref, "button"); // div
  return <div ref={ref} {...props} />;
}

useAttribute

function useAttribute(
  refOrElement: RefObject<HTMLElement | null> | HTMLElement | null,
  attributeName: string,
  defaultValue?: string,
): string | undefined;

Returns the attribute value of an element.

Example:

function Component(props) {
  const ref = React.useRef();
  const role = useAttribute(ref, "role", props.role);
  return <div ref={ref} {...props} />;
}

useUpdateEffect

function useUpdateEffect(effect: EffectCallback, deps?: DependencyList): void;

A React.useEffect that will not run on the first render.

useUpdateLayoutEffect

function useUpdateLayoutEffect(
  effect: EffectCallback,
  deps?: DependencyList,
): void;

A React.useLayoutEffect that will not run on the first render.

useForceUpdate

function useForceUpdate(): [never[], React.ActionDispatch<[]>];

A React hook similar to useState and useReducer, but with the only purpose of re-rendering the component.

useBooleanEvent

function useBooleanEvent<T extends unknown[]>(
  booleanOrCallback: boolean | ((...args: T) => boolean),
): (...args: T) => boolean;

Returns an event callback similar to useEvent, but this also accepts a boolean value, which will be turned into a function.

useWrapElement

function useWrapElement<P>(
  props: P & { wrapElement?: WrapElement },
  callback: WrapElement,
  deps: DependencyList = [],
): P & { wrapElement: WrapElement };

Returns props with an additional wrapElement prop.

usePortalRef

function usePortalRef(
  portalProp = false,
  portalRefProp?:
    RefCallback<HTMLElement> | MutableRefObject<HTMLElement | null>,
): {
  portalRef: ((value: unknown) => (() => void) | undefined) | undefined;
  portalNode: HTMLElement | null;
  domReady: true | HTMLElement | null;
};

Merges the portalRef prop and returns a domReady to be used in the components that use Portal underneath.

useMetadataProps

function useMetadataProps<T, K extends keyof any>(
  props: { onLoadedMetadataCapture?: AnyFunction & { [key in K]?: T } },
  key: K,
  value: T,
): readonly [
  (AnyFunction & { [key in K]?: T | undefined })[K] | undefined,
  { readonly onLoadedMetadataCapture: any },
];

A hook that passes metadata props around without leaking them to the DOM.

useIsMouseMoving

function useIsMouseMoving(): () => boolean;

Returns a function that checks whether the mouse is moving.

General utilities

Helpers for working with refs, elements, and props.

setRef

function setRef<T>(
  ref: RefCallback<T> | MutableRefObject<T> | null | undefined,
  value: T,
): void | (() => void);

Sets both a function and object React ref.

Returns a callback ref cleanup function when one is provided.

isValidElementWithRef

function isValidElementWithRef<P extends { ref?: Ref<any> }>(
  element: unknown,
): element is ReactElement<P> & { ref?: Ref<any> };

Checks if an element is a valid React element with a ref.

getRefProperty

function getRefProperty(element: unknown): Ref<any> | undefined;

Gets the ref property from a React element.

mergeProps

function mergeProps<T extends HTMLAttributes<any>>(base: T, overrides: T): T;

Merges two sets of props.

System utilities

Helpers for creating and composing Ariakit React components.

forwardRef

function forwardRef<T extends React.FC<any>>(render: T): T;

The same as React.forwardRef but passes the ref as a prop and returns a component with the same generic type.

Props holding undefined are dropped, so passing one behaves the same as omitting it and the component keeps the value it computes for itself.

memo

function memo<T extends React.FC<any>>(
  Component: T,
  propsAreEqual?: (
    prevProps: Readonly<React.ComponentPropsWithoutRef<T>>,
    nextProps: Readonly<React.ComponentPropsWithoutRef<T>>,
  ) => boolean,
): T;

The same as React.memo but returns a component with the same generic type.

createElement

function createElement(
  Type: React.ElementType,
  props: Props<React.ElementType, Options>,
): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;

Creates a React element that supports the render and wrapElement props.

createHook

function createHook<
  T extends React.ElementType,
  P extends AnyObject = EmptyObject,
>(useProps: (props: Props<T, P>) => HTMLProps<T, P>): Hook<T, P>;

Creates a component hook that accepts props and returns props so they can be passed to a React element.

createStoreContext

type StoreProvider<T extends Store> = React.ComponentType<{
  value: T | undefined;
  children?: React.ReactNode;
}>;

function createStoreContext<T extends Store>(
  providers: StoreProvider<T>[] = [],
  scopedProviders: StoreProvider<T>[] = [],
): {
  context: React.Context<T | undefined>;
  scopedContext: React.Context<T | undefined>;
  useContext: () => T | undefined;
  useScopedContext: (onlyScoped?: boolean) => T | undefined;
  useProviderContext: () => T | undefined;
  ContextProvider: (
    props: React.ComponentPropsWithoutRef<React.Provider<T | undefined>>,
  ) => React.JSX.Element;
  ScopedContextProvider: (
    props: React.ComponentPropsWithoutRef<React.Provider<T | undefined>>,
  ) => React.JSX.Element;
};

Creates an Ariakit store context with hooks and provider components.

Type utilities

Shared types for Ariakit React components.

RenderProp

type RenderProp<P = React.HTMLAttributes<any> & { ref?: React.Ref<any> }> = (
  props: P,
) => React.ReactNode;

Render prop type.

Example:

const children: RenderProp = (props) => <div {...props} />;

WrapElement

type WrapElement = (element: React.ReactElement) => React.ReactElement;

The wrapElement prop.

Options

interface Options {
  wrapElement?: WrapElement;
  /**
   * Allows the component to be rendered as a different HTML element or React
   * component. The value can be a React element or a function that takes in the
   * original component props and gives back a React element with the props
   * merged.
   *
   * Some Ariakit components detect the type of the underlying element when they
   * mount. If the render element's type may change while the component is
   * mounted, pass a
   * [`key`](https://react.dev/learn/preserving-and-resetting-state) prop that
   * changes with the element type so React remounts the component with the new
   * element. Remounting resets uncontrolled state, so keep the relevant state
   // ... 11 more lines
   * for more details.
   */
  render?: RenderProp | React.ReactElement;
}

Custom props including the render prop.

HTMLProps

type HTMLProps<
  T extends React.ElementType,
  P extends AnyObject = EmptyObject,
> = Omit<React.ComponentPropsWithRef<T>, keyof P> & {
  [index: `data-${string}`]: unknown;
};

HTML props based on the element type, excluding custom props.

Example:

type ButtonHTMLProps = HTMLProps<"button", { custom?: boolean }>;

Props

type Props<T extends React.ElementType, P extends AnyObject = EmptyObject> = P &
  HTMLProps<T, P>;

Props based on the element type, including custom props.

Hook

type Hook<T extends React.ElementType, P extends AnyObject = EmptyObject> = <
  ElementType extends React.ElementType = T,
>(
  props?: Props<ElementType, P>,
) => HTMLProps<ElementType, P>;

A component hook that supports the render prop and returns HTML props based on the element type.

Example:

type UseButton = Hook<"button", { custom?: boolean }>;