From 3445cc32402c35fbd427d58b4e639972caafa0f5 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 23 Jul 2026 17:33:35 -0400
Subject: [PATCH] feat(headless): add useRender hook alongside renderElement

Introduces a base-ui-style useRender hook: a render prop that accepts a
React element (render={<Link/>}) or a function, with internal ref merging
and state-to-data-attribute mapping. renderElement stays exported for the
phased migration. Migrates Mosaic Box, Heading, Text and the dialog
trigger/popup primitives onto the hook.
---
 .changeset/mosaic-use-render.md               |   2 +
 .../src/primitives/dialog/dialog-popup.tsx    |  37 ++--
 .../src/primitives/dialog/dialog-trigger.tsx  |  17 +-
 packages/headless/src/utils/index.ts          |   1 +
 .../headless/src/utils/render-element.tsx     |   2 +-
 .../headless/src/utils/use-render.test.tsx    | 189 ++++++++++++++++++
 packages/headless/src/utils/use-render.tsx    | 126 ++++++++++++
 packages/ui/src/mosaic/components/heading.tsx |  24 ++-
 packages/ui/src/mosaic/components/text.tsx    |  22 +-
 packages/ui/src/mosaic/primitives/box.tsx     |   6 +-
 10 files changed, 382 insertions(+), 44 deletions(-)
 create mode 100644 .changeset/mosaic-use-render.md
 create mode 100644 packages/headless/src/utils/use-render.test.tsx
 create mode 100644 packages/headless/src/utils/use-render.tsx

diff --git a/.changeset/mosaic-use-render.md b/.changeset/mosaic-use-render.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-use-render.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/headless/src/primitives/dialog/dialog-popup.tsx b/packages/headless/src/primitives/dialog/dialog-popup.tsx
index 45f68b9ee84..6e11828a734 100644
--- a/packages/headless/src/primitives/dialog/dialog-popup.tsx
+++ b/packages/headless/src/primitives/dialog/dialog-popup.tsx
@@ -1,9 +1,9 @@
 'use client';
 
-import { FloatingFocusManager, useMergeRefs } from '@floating-ui/react';
+import { FloatingFocusManager } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
 import { useDialogContext } from './dialog-context';
 
 /** Props for {@link DialogPopup}. */
@@ -15,35 +15,36 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
   const { popupRef, refs, getFloatingProps, floatingContext, modal, labelId, descriptionId, mounted, transitionProps } =
     useDialogContext();
 
-  // floating-ui types `setFloating` as a method signature, but at runtime it's
-  // a stable callback that doesn't use `this`, so the unbound-method check is a
-  // false positive here.
-  // eslint-disable-next-line @typescript-eslint/unbound-method
-  const combinedRef = useMergeRefs([popupRef, refs.setFloating, ref]);
-
-  if (!mounted) {
-    return null;
-  }
-
   const ownProps = {
-    ref: combinedRef,
     'aria-labelledby': labelId,
     'aria-describedby': descriptionId,
   } satisfies DefaultProps<'div'>;
 
   const defaultProps = { ...ownProps, ...getFloatingProps(), ...transitionProps };
 
+  const element = useRender({
+    defaultTagName: 'div',
+    render,
+    enabled: mounted,
+    // floating-ui types `setFloating` as a method signature, but at runtime it's
+    // a stable callback that doesn't use `this`, so the unbound-method check is a
+    // false positive here.
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    ref: [popupRef, refs.setFloating, ref],
+    props: mergeProps<'div'>(defaultProps, otherProps),
+  });
+
+  if (!element) {
+    return null;
+  }
+
   return (
     <FloatingFocusManager
       context={floatingContext}
       modal={modal}
       outsideElementsInert={modal}
     >
-      {renderElement({
-        defaultTagName: 'div',
-        render,
-        props: mergeProps<'div'>(defaultProps, otherProps),
-      })}
+      {element}
     </FloatingFocusManager>
   );
 });
diff --git a/packages/headless/src/primitives/dialog/dialog-trigger.tsx b/packages/headless/src/primitives/dialog/dialog-trigger.tsx
index 168e4bb1b51..33cc82b4263 100644
--- a/packages/headless/src/primitives/dialog/dialog-trigger.tsx
+++ b/packages/headless/src/primitives/dialog/dialog-trigger.tsx
@@ -1,9 +1,8 @@
 'use client';
 
-import { useMergeRefs } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, type DefaultProps, mergeProps, renderElement } from '../../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
 import { useDialogContext } from './dialog-context';
 
 /** Props for {@link DialogTrigger}. */
@@ -15,24 +14,22 @@ export const DialogTrigger = React.forwardRef<HTMLButtonElement, DialogTriggerPr
     const { render, ...otherProps } = props;
     const { open, refs, getReferenceProps } = useDialogContext();
 
-    // floating-ui types `setReference` as a method signature, but at runtime it's
-    // a stable callback that doesn't use `this`, so the unbound-method check is a
-    // false positive here.
-    // eslint-disable-next-line @typescript-eslint/unbound-method
-    const combinedRef = useMergeRefs([refs.setReference, ref]);
-
     const state = { open };
 
     const ownProps = {
       type: 'button',
-      ref: combinedRef,
     } satisfies DefaultProps<'button'>;
 
     const defaultProps = { ...ownProps, ...getReferenceProps() };
 
-    return renderElement({
+    return useRender({
       defaultTagName: 'button',
       render,
+      // floating-ui types `setReference` as a method signature, but at runtime it's
+      // a stable callback that doesn't use `this`, so the unbound-method check is a
+      // false positive here.
+      // eslint-disable-next-line @typescript-eslint/unbound-method
+      ref: [refs.setReference, ref],
       state,
       stateAttributesMapping: {
         open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
diff --git a/packages/headless/src/utils/index.ts b/packages/headless/src/utils/index.ts
index a0fc997f94a..eae4ccedc32 100644
--- a/packages/headless/src/utils/index.ts
+++ b/packages/headless/src/utils/index.ts
@@ -1,3 +1,4 @@
 export { cssVars } from './css-vars';
 export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';
+export { useRender } from './use-render';
diff --git a/packages/headless/src/utils/render-element.tsx b/packages/headless/src/utils/render-element.tsx
index 8d2b56ecb8c..170dc75d588 100644
--- a/packages/headless/src/utils/render-element.tsx
+++ b/packages/headless/src/utils/render-element.tsx
@@ -34,7 +34,7 @@ export type DefaultProps<Tag extends keyof React.JSX.IntrinsicElements> = React.
 /**
  * Maps state keys to functions that return data-attribute objects (or null).
  */
-type StateAttributesMapping<S> = {
+export type StateAttributesMapping<S> = {
   [K in keyof S]?: (value: S[K]) => Record<string, string> | null;
 };
 
diff --git a/packages/headless/src/utils/use-render.test.tsx b/packages/headless/src/utils/use-render.test.tsx
new file mode 100644
index 00000000000..6589b95c7b8
--- /dev/null
+++ b/packages/headless/src/utils/use-render.test.tsx
@@ -0,0 +1,189 @@
+import { cleanup, render, renderHook, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { useRender } from './use-render';
+
+afterEach(() => {
+  cleanup();
+});
+
+describe('useRender', () => {
+  it('renders the default tag when no render prop', () => {
+    function C() {
+      return useRender({ defaultTagName: 'span', props: { 'data-testid': 'test', children: 'hello' } });
+    }
+    render(<C />);
+
+    const el = screen.getByTestId('test');
+    expect(el.tagName).toBe('SPAN');
+    expect(el).toHaveTextContent('hello');
+  });
+
+  it('renders via a render function', () => {
+    function C() {
+      return useRender({
+        defaultTagName: 'div',
+        render: props => <article {...props} />,
+        props: { 'data-testid': 'test', children: 'content' },
+      });
+    }
+    render(<C />);
+
+    expect(screen.getByTestId('test').tagName).toBe('ARTICLE');
+  });
+
+  it('renders via a render element (clones it)', () => {
+    function C() {
+      return useRender({
+        defaultTagName: 'div',
+        render: <article data-variant='x' />,
+        props: { 'data-testid': 'test', children: 'content' },
+      });
+    }
+    render(<C />);
+
+    const el = screen.getByTestId('test');
+    expect(el.tagName).toBe('ARTICLE');
+    expect(el).toHaveAttribute('data-variant', 'x');
+    expect(el).toHaveTextContent('content');
+  });
+
+  it('returns null when enabled is false', () => {
+    const { result } = renderHook(() =>
+      useRender({ defaultTagName: 'div', enabled: false, props: { children: 'hidden' } }),
+    );
+    expect(result.current).toBeNull();
+  });
+
+  it('applies state attributes via stateAttributesMapping', () => {
+    function C() {
+      return useRender({
+        defaultTagName: 'button',
+        state: { open: true },
+        stateAttributesMapping: {
+          open: (v: boolean): Record<string, string> | null => (v ? { 'data-cl-open': '' } : { 'data-cl-closed': '' }),
+        },
+        props: { 'data-testid': 'test' },
+      });
+    }
+    render(<C />);
+
+    const el = screen.getByTestId('test');
+    expect(el).toHaveAttribute('data-cl-open', '');
+    expect(el).not.toHaveAttribute('data-cl-closed');
+  });
+
+  it('merges a single ref onto the rendered element', () => {
+    const ref = React.createRef<HTMLDivElement>();
+    function C() {
+      return useRender({ defaultTagName: 'div', ref, props: { 'data-testid': 'test' } });
+    }
+    render(<C />);
+
+    expect(ref.current).toBe(screen.getByTestId('test'));
+  });
+
+  it('merges an array of refs onto the rendered element', () => {
+    const refA = React.createRef<HTMLDivElement>();
+    const refB = vi.fn();
+    function C() {
+      return useRender({ defaultTagName: 'div', ref: [refA, refB], props: { 'data-testid': 'test' } });
+    }
+    render(<C />);
+
+    const el = screen.getByTestId('test');
+    expect(refA.current).toBe(el);
+    expect(refB).toHaveBeenCalledWith(el);
+  });
+
+  it("merges a render element's own ref with the params ref", () => {
+    const paramRef = React.createRef<HTMLElement>();
+    const elementRef = React.createRef<HTMLElement>();
+    function C() {
+      return useRender({
+        defaultTagName: 'div',
+        ref: paramRef,
+        render: (
+          <article
+            ref={elementRef}
+            data-testid='test'
+          />
+        ),
+      });
+    }
+    render(<C />);
+
+    const el = screen.getByTestId('test');
+    expect(paramRef.current).toBe(el);
+    expect(elementRef.current).toBe(el);
+  });
+
+  it('concatenates className when cloning a render element', () => {
+    function C() {
+      return useRender({
+        defaultTagName: 'div',
+        render: (
+          <article
+            className='from-element'
+            data-testid='test'
+          />
+        ),
+        props: { className: 'from-part' },
+      });
+    }
+    render(<C />);
+
+    expect(screen.getByTestId('test')).toHaveClass('from-part', 'from-element');
+  });
+
+  it('chains event handlers when cloning a render element', () => {
+    const partHandler = vi.fn();
+    const elementHandler = vi.fn();
+    function C() {
+      return useRender({
+        defaultTagName: 'button',
+        render: (
+          <button
+            type='button'
+            onClick={elementHandler}
+            data-testid='test'
+          />
+        ),
+        props: { onClick: partHandler },
+      });
+    }
+    render(<C />);
+
+    screen.getByTestId('test').click();
+
+    expect(partHandler).toHaveBeenCalledTimes(1);
+    expect(elementHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes computed props plus a merged ref to the render function', () => {
+    const ref = React.createRef<HTMLDivElement>();
+    const renderFn = vi.fn((props: React.HTMLAttributes<HTMLDivElement>) => <div {...props} />);
+    function C() {
+      return useRender({
+        defaultTagName: 'div',
+        render: renderFn,
+        ref,
+        state: { open: true },
+        stateAttributesMapping: {
+          open: (v: boolean) => (v ? { 'data-cl-open': '' } : null),
+        },
+        props: { id: 'test' },
+      });
+    }
+    render(<C />);
+
+    expect(renderFn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'test',
+        'data-cl-open': '',
+        ref: expect.any(Function),
+      }),
+    );
+  });
+});
diff --git a/packages/headless/src/utils/use-render.tsx b/packages/headless/src/utils/use-render.tsx
new file mode 100644
index 00000000000..32c4093f3ff
--- /dev/null
+++ b/packages/headless/src/utils/use-render.tsx
@@ -0,0 +1,126 @@
+import { useMergeRefs } from '@floating-ui/react';
+import * as React from 'react';
+
+import type { DefaultProps, RenderProp, StateAttributesMapping } from './render-element';
+import { mergeProps } from './render-element';
+
+/**
+ * A `render` prop: a render function, or a React element to clone with the
+ * part's computed props (`render={<Link/>}`).
+ */
+type RenderPropOrElement<Tag extends keyof React.JSX.IntrinsicElements> =
+  | RenderProp<React.ComponentPropsWithRef<Tag>>
+  | React.ReactElement;
+
+/**
+ * Reads the ref off a React element passed to `render`. React 19 exposes it on
+ * `props.ref`; React <=18 keeps it on the element itself.
+ */
+function getReactElementRef(element: React.ReactElement): React.Ref<unknown> | undefined {
+  // SAFETY: `@types/react` types `props`/`ref` too loosely to read `ref` off an
+  // arbitrary element without a cast. React guarantees `ref` is a `React.Ref` when
+  // present; both shapes are checked and either branch is undefined-safe.
+  const fromProps = (element.props as { ref?: React.Ref<unknown> }).ref;
+  if (fromProps != null) {
+    return fromProps;
+  }
+  return (element as { ref?: React.Ref<unknown> }).ref ?? undefined;
+}
+
+interface UseRenderParamsBase<
+  Tag extends keyof React.JSX.IntrinsicElements,
+  State extends Record<string, unknown> = Record<string, never>,
+> {
+  /** Fallback HTML tag when `render` is not provided. */
+  defaultTagName: Tag;
+  /** Render prop or element from the consumer. */
+  render?: RenderPropOrElement<Tag>;
+  /** Ref(s) to merge onto the rendered element. Merged with the element's own ref. */
+  ref?: React.Ref<unknown> | Array<React.Ref<unknown> | undefined>;
+  /** State object. Keys are mapped to data attributes via `stateAttributesMapping`. */
+  state?: State;
+  /** Custom mapping from state keys to data-attribute objects. */
+  stateAttributesMapping?: StateAttributesMapping<State>;
+  /** Props to spread onto the element. Pass refs via `ref`, not here. */
+  props?: DefaultProps<Tag> | Record<string, unknown>;
+}
+
+interface UseRenderParamsConditional<
+  Tag extends keyof React.JSX.IntrinsicElements,
+  State extends Record<string, unknown> = Record<string, never>,
+> extends UseRenderParamsBase<Tag, State> {
+  /** When false, returns null (used by Positioners gated on `mounted`). */
+  enabled: boolean;
+}
+
+interface UseRenderParamsAlways<
+  Tag extends keyof React.JSX.IntrinsicElements,
+  State extends Record<string, unknown> = Record<string, never>,
+> extends UseRenderParamsBase<Tag, State> {
+  enabled?: never;
+}
+
+/**
+ * Renders a primitive part with render-prop support, conditional rendering, and
+ * state-to-data-attribute mapping. Unlike `renderElement`, `render` accepts a
+ * React element (cloned with merged props) as well as a function, and refs are
+ * merged internally via `ref`.
+ *
+ * Hook: call it unconditionally. When `enabled` is omitted the element is always
+ * rendered (returns ReactElement); when passed it may be skipped (returns null).
+ */
+export function useRender<
+  Tag extends keyof React.JSX.IntrinsicElements,
+  State extends Record<string, unknown> = Record<string, never>,
+>(params: UseRenderParamsAlways<Tag, State>): React.ReactElement;
+export function useRender<
+  Tag extends keyof React.JSX.IntrinsicElements,
+  State extends Record<string, unknown> = Record<string, never>,
+>(params: UseRenderParamsConditional<Tag, State>): React.ReactElement | null;
+export function useRender<
+  Tag extends keyof React.JSX.IntrinsicElements,
+  State extends Record<string, unknown> = Record<string, never>,
+>(params: UseRenderParamsBase<Tag, State> & { enabled?: boolean }): React.ReactElement | null {
+  const { defaultTagName, render, ref, enabled = true, state, stateAttributesMapping, props } = params;
+
+  const normalizedRefs = ref == null ? [] : Array.isArray(ref) ? ref : [ref];
+  const elementRef = React.isValidElement(render) ? getReactElementRef(render) : undefined;
+  const mergedRef = useMergeRefs([...normalizedRefs, elementRef]);
+
+  if (!enabled) {
+    return null;
+  }
+
+  let dataAttrs: Record<string, string> = {};
+  if (state && stateAttributesMapping) {
+    for (const key of Object.keys(stateAttributesMapping) as Array<keyof State>) {
+      const mapper = stateAttributesMapping[key];
+      if (mapper) {
+        const attrs = mapper(state[key]);
+        if (attrs) {
+          dataAttrs = { ...dataAttrs, ...attrs };
+        }
+      }
+    }
+  }
+
+  const computedProps = { ...props, ...dataAttrs };
+
+  if (typeof render === 'function') {
+    // SAFETY: computedProps is the tag's props widened with data-* attrs; the render
+    // function is declared to receive this tag's props. Matches renderElement above.
+    return render({ ...computedProps, ref: mergedRef } as React.ComponentPropsWithRef<Tag>);
+  }
+
+  if (React.isValidElement(render)) {
+    // SAFETY: `@types/react` types element `props` as `unknown`; mergeProps reads it
+    // as an untyped bag of props, which is exactly what a cloned element carries.
+    const merged = mergeProps<Tag>(computedProps, render.props as Record<string, unknown>);
+    // SAFETY: cloneElement's prop type omits `ref`, but React re-associates a ref passed
+    // here at runtime (base-ui clones render elements the same way). Asserting the element's
+    // props as an untyped bag lets the merged props + ref through the index signature.
+    return React.cloneElement(render as React.ReactElement<Record<string, unknown>>, { ...merged, ref: mergedRef });
+  }
+
+  return React.createElement(defaultTagName, { ...computedProps, ref: mergedRef });
+}
diff --git a/packages/ui/src/mosaic/components/heading.tsx b/packages/ui/src/mosaic/components/heading.tsx
index d09c777b064..e018da5258f 100644
--- a/packages/ui/src/mosaic/components/heading.tsx
+++ b/packages/ui/src/mosaic/components/heading.tsx
@@ -1,5 +1,5 @@
-import type { ComponentProps } from '@clerk/headless/utils';
-import { renderElement } from '@clerk/headless/utils';
+import type { ComponentProps, RenderProp } from '@clerk/headless/utils';
+import { useRender } from '@clerk/headless/utils';
 import React from 'react';
 
 import type { RecipeVariantProps } from '../slot-recipe';
@@ -44,7 +44,9 @@ declare module '../registry' {
 }
 
 /** Props for the Heading component combining h2 attributes with recipe variants. */
-export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
+export type HeadingProps = Omit<ComponentProps<'h2'>, 'render'> & {
+  render?: RenderProp<React.ComponentPropsWithRef<'h2'>> | React.ReactElement;
+} & RecipeVariantProps<typeof headingRecipe>;
 
 export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
 
@@ -56,11 +58,19 @@ export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(
 export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
   const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
   const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
-  if (render) {
-    // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.
-    return renderElement({ defaultTagName: 'h2', render, props: { ref, ...root, ...rest } as Record<string, unknown> });
+  // useRender only runs for `render` (function or element); Emotion processes `css`
+  // inside the consumer's own JSX there. The no-render fallback must stay JSX —
+  // React.createElement bypasses Emotion's factory, leaking css to the DOM.
+  const element = useRender({
+    defaultTagName: 'h2',
+    render,
+    ref,
+    enabled: Boolean(render),
+    props: { ...root, ...rest },
+  });
+  if (element) {
+    return element;
   }
-  // Fallback must be JSX — React.createElement bypasses Emotion's factory, leaking css to the DOM.
   return (
     <h2
       ref={ref}
diff --git a/packages/ui/src/mosaic/components/text.tsx b/packages/ui/src/mosaic/components/text.tsx
index 45d5a6c80d4..37477935f42 100644
--- a/packages/ui/src/mosaic/components/text.tsx
+++ b/packages/ui/src/mosaic/components/text.tsx
@@ -1,5 +1,5 @@
-import type { ComponentProps } from '@clerk/headless/utils';
-import { renderElement } from '@clerk/headless/utils';
+import type { ComponentProps, RenderProp } from '@clerk/headless/utils';
+import { useRender } from '@clerk/headless/utils';
 import React from 'react';
 
 import type { RecipeVariantProps } from '../slot-recipe';
@@ -42,7 +42,9 @@ declare module '../registry' {
 }
 
 /** Props for the Text component combining p element attributes with recipe variants. */
-export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
+export type TextProps = Omit<ComponentProps<'p'>, 'render'> & {
+  render?: RenderProp<React.ComponentPropsWithRef<'p'>> | React.ReactElement;
+} & RecipeVariantProps<typeof textRecipe>;
 
 export const TextContext = React.createContext<Partial<TextProps> | null>(null);
 
@@ -54,8 +56,18 @@ export const TextContext = React.createContext<Partial<TextProps> | null>(null);
 export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
   const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
   const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
-  if (render) {
-    return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });
+  // useRender only runs for `render` (function or element); Emotion processes `css`
+  // inside the consumer's own JSX there. The no-render fallback must stay JSX —
+  // React.createElement bypasses Emotion's factory, leaking css to the DOM.
+  const element = useRender({
+    defaultTagName: 'p',
+    render,
+    ref,
+    enabled: Boolean(render),
+    props: { ...root, ...rest },
+  });
+  if (element) {
+    return element;
   }
   return (
     <p
diff --git a/packages/ui/src/mosaic/primitives/box.tsx b/packages/ui/src/mosaic/primitives/box.tsx
index fda9910749e..b5269bf93f7 100644
--- a/packages/ui/src/mosaic/primitives/box.tsx
+++ b/packages/ui/src/mosaic/primitives/box.tsx
@@ -1,4 +1,4 @@
-import { type ComponentProps, renderElement, type RenderProp } from '@clerk/headless/utils';
+import { type ComponentProps, type RenderProp, useRender } from '@clerk/headless/utils';
 import React from 'react';
 
 /**
@@ -10,10 +10,10 @@ import React from 'react';
  * Accepts render prop with any element type — styling passes along regardless of what's rendered.
  */
 export type BoxProps = Omit<ComponentProps<'div'>, 'render'> & {
-  render?: RenderProp<React.HTMLAttributes<HTMLElement>>;
+  render?: RenderProp<React.HTMLAttributes<HTMLElement>> | React.ReactElement;
 };
 
 export const Box = React.forwardRef<HTMLElement, BoxProps>(function Box(props, ref) {
   const { render, ...rest } = props;
-  return renderElement({ defaultTagName: 'div', render, props: { ...rest, ref } });
+  return useRender({ defaultTagName: 'div', render, ref, props: rest });
 });