useRender

Hook for enabling a render prop in custom components.

The useRender hook lets you build custom components that provide a render prop to override the default rendered element.

Examples

A render prop for a custom Text component lets consumers use it to replace the default rendered p element with a different tag or component.

Text component rendered as a paragraph tag

Text component rendered as a strong tag

index.tsx index.module.css theme.css

'use client';
import { useRender } from '@base-ui/react/use-render';
import { mergeProps } from '@base-ui/react/merge-props';
import styles from './index.module.css';

interface TextProps extends useRender.ComponentProps<'p'> {}

function Text(props: TextProps) {
  const { render, ...otherProps } = props;

  const element = useRender({
    defaultTagName: 'p',
    render,
    props: mergeProps<'p'>({ className: styles.Text }, otherProps),
  });

  return element;
}

export default function ExampleText() {
  return (
    <div>
      <Text>Text component rendered as a paragraph tag</Text>
      <Text render={<strong />}>Text component rendered as a strong tag</Text>
    </div>
  );
}

The callback version of the render prop enables more control of how props are spread, and also passes the internal state of a component.

index.tsx index.module.css theme.css

'use client';
import * as React from 'react';
import { useRender } from '@base-ui/react/use-render';
import { mergeProps } from '@base-ui/react/merge-props';
import styles from './index.module.css';

interface CounterState {
  odd: boolean;
}

interface CounterProps extends useRender.ComponentProps<'button', CounterState> {}

function Counter(props: CounterProps) {
  const { render, ...otherProps } = props;

  const [count, setCount] = React.useState(0);
  const odd = count % 2 === 1;
  const state = React.useMemo(() => ({ odd }), [odd]);

  const defaultProps: useRender.ElementProps<'button'> = {
    className: styles.Button,
    type: 'button',
    children: (
      <React.Fragment>
        Counter: <span>{count}</span>
      </React.Fragment>
    ),
    onClick() {
      setCount((prev) => prev + 1);
    },
    'aria-label': `Count is ${count}, click to increase.`,
  };

  const element = useRender({
    defaultTagName: 'button',
    render,
    state,
    props: mergeProps<'button'>(defaultProps, otherProps),
  });

  return element;
}

export default function ExampleCounter() {
  return (
    <Counter
      render={(props, state) => (
        <button {...props}>
          {props.children}
          <span className={styles.suffix}>{state.odd ? '👎' : '👍'}</span>
        </button>
      )}
    />
  );
}

Merging props

The mergeProps function merges two or more sets of React props together. It safely merges three types of props:

Event handlers, so that all are invoked
className strings
style properties

mergeProps merges objects from left to right, so that subsequent objects’ properties in the arguments overwrite previous ones. Merging props is useful when creating custom components, as well as inside the callback version of the render prop for any Base UI component.

Using mergeProps in the render callback

import { mergeProps } from '@base-ui/react/merge-props';
import styles from './index.module.css';

function Button() {
  return (
    <Component
      render={(props, state) => (
        <button
          {...mergeProps<'button'>(props, {
            className: styles.Button,
          })}
        />
      )}
    />
  );
}

Merging refs

When building custom components, you often need to control a ref internally while still letting external consumers pass their own—merging refs lets both parties have access to the underlying DOM element. The ref option in useRender enables this, which holds an array of refs to be merged together.

In React 19, React.forwardRef() is not needed when building primitive components, as the external ref prop is already contained inside props. Your internal ref can be passed to ref to be merged with props.ref:

React 19

function Text({ render, ...props }: TextProps) {
  const internalRef = React.useRef<HTMLElement | null>(null);

  const element = useRender({
    defaultTagName: 'p',
    ref: internalRef,
    props,
    render,
  });

  return element;
}

In older versions of React, you need to use React.forwardRef() and add the forwarded ref to the ref array along with your own internal ref.

The examples above assume React 19, and should be modified to use React.forwardRef() to support React 18 and 17.

React 18 and 17

const Text = React.forwardRef(function Text(
  { render, ...props }: TextProps,
  forwardedRef: React.ForwardedRef<HTMLElement>,
) {
  const internalRef = React.useRef<HTMLElement | null>(null);

  const element = useRender({
    defaultTagName: 'p',
    ref: [forwardedRef, internalRef],
    props,
    render,
  });

  return element;
});

TypeScript

To type props, there are two interfaces:

useRender.ComponentProps for a component’s external (public) props. It types the render prop and HTML attributes.
useRender.ElementProps for the element’s internal (private) props. It types HTML attributes alone.

Typing props

interface ButtonProps extends useRender.ComponentProps<'button'> {}

function Button({ render, ...props }: ButtonProps) {
  const defaultProps: useRender.ElementProps<'button'> = {
    className: styles.Button,
    type: 'button',
    children: 'Click me',
  };

  const element = useRender({
    defaultTagName: 'button',
    render,
    props: mergeProps<'button'>(defaultProps, props),
  });

  return element;
}

Migrating from Radix UI

Radix UI uses an asChild prop, while Base UI uses a render prop. Learn more about how composition works in Base UI in the composition guide.

In Radix UI, the Slot component lets you implement an asChild prop.

Radix UI Slot component

import { Slot } from 'radix-ui';

function Button({ asChild, ...props }) {
  const Comp = asChild ? Slot.Root : 'button';
  return <Comp {...props} />;
}

// Usage
<Button asChild>
  <a href="/contact">Contact</a>
</Button>

In Base UI, useRender lets you implement a render prop. The example below is the equivalent implementation to the Radix example above.

Base UI render prop

import { useRender } from '@base-ui/react/use-render';

function Button({ render, ...props }) {
  return useRender({
    defaultTagName: 'button',
    render,
    props,
  });
}

// Usage
<Button render={<a href="/contact" />}>Contact</Button>

API reference

Usage

const element = useRender({
  // Input parameters
});

render^*

ReactElement | function

—

Name: render
Description: The React element or a function that returns one to override the default element.
Type: | UseRenderRenderProp<Record<string, unknown>> | undefined

ref^*

Union

—

Name: ref
Description: The ref to apply to the rendered element.
Type: | React.Ref<Element>[] | React.Ref<Element> | undefined

state^*

Record<string, unknown>

—

Name: state
Description: The state of the component, passed as the second argument to the render callback. State properties are automatically converted to data-* attributes.
Type: Record<string, unknown> | undefined

stateAttributesMapping^*

StateAttributesMapping<Record<string, unknown>>

—

Name: stateAttributesMapping
Description: Custom mapping for converting state properties to data-* attributes.
Type: StateAttributesMapping<Record<string, unknown>> | undefined
Example: { isActive: (value) => (value ? { ‘data-is-active’: ‘’ } : null) }

props^*

Record<string, unknown>

—

Name: props
Description: Props to be spread on the rendered element. They are merged with the internal props of the component, so that event handlers are merged, className strings and style properties are joined, while other external props overwrite the internal ones.
Type: Record<string, unknown> | undefined

enabled^*

boolean

—

Name: enabled
Description: If false, the hook will skip most of its internal logic and return null. This is useful for rendering a component conditionally.
Type: boolean | undefined
Default: true

defaultTagName^*

Union

—

Name: defaultTagName
Description: The default tag name to use for the rendered element when render is not provided.
Type: | 'symbol' | 'object' | 'a' | 'abbr' | 'address' | 'area' | 'article' | 'aside' | 'audio' | 'b' | 'base' | 'bdi' | 'bdo' | 'big' | 'blockquote' | 'body' | 'br' | 'button' | 'canvas' | 'caption' | 'center' | 'cite' | 'code' | 'col' | 'colgroup' | 'data' | 'datalist' | 'dd' | 'del' | 'details' | 'dfn' | 'dialog' | 'div' | 'dl' | 'dt' | 'em' | 'embed' | 'fieldset' | 'figcaption' | 'figure' | 'footer' | 'form' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'head' | 'header' | 'hgroup' | 'hr' | 'html' | 'i' | 'iframe' | 'img' | 'input' | 'ins' | 'kbd' | 'keygen' | 'label' | 'legend' | 'li' | 'link' | 'main' | 'map' | 'mark' | 'menu' | 'menuitem' | 'meta' | 'meter' | 'nav' | 'noindex' | 'noscript' | 'ol' | 'optgroup' | 'option' | 'output' | 'p' | 'param' | 'picture' | 'pre' | 'progress' | 'q' | 'rp' | 'rt' | 'ruby' | 's' | 'samp' | 'search' | 'slot' | 'script' | 'section' | 'select' | 'small' | 'source' | 'span' | 'strong' | 'style' | 'sub' | 'summary' | 'sup' | 'table' | 'template' | 'tbody' | 'td' | 'textarea' | 'tfoot' | 'th' | 'thead' | 'time' | 'title' | 'tr' | 'track' | 'u' | 'ul' | 'var' | 'video' | 'wbr' | 'webview' | 'svg' | 'animate' | 'animateMotion' | 'animateTransform' | 'circle' | 'clipPath' | 'defs' | 'desc' | 'ellipse' | 'feBlend' | 'feColorMatrix' | 'feComponentTransfer' | 'feComposite' | 'feConvolveMatrix' | 'feDiffuseLighting' | 'feDisplacementMap' | 'feDistantLight' | 'feDropShadow' | 'feFlood' | 'feFuncA' | 'feFuncB' | 'feFuncG' | 'feFuncR' | 'feGaussianBlur' | 'feImage' | 'feMerge' | 'feMergeNode' | 'feMorphology' | 'feOffset' | 'fePointLight' | 'feSpecularLighting' | 'feSpotLight' | 'feTile' | 'feTurbulence' | 'filter' | 'foreignObject' | 'g' | 'image' | 'line' | 'linearGradient' | 'marker' | 'mask' | 'metadata' | 'mpath' | 'path' | 'pattern' | 'polygon' | 'polyline' | 'radialGradient' | 'rect' | 'set' | 'stop' | 'switch' | 'text' | 'textPath' | 'tspan' | 'use' | 'view' | undefined
Default: 'div'

Return value

ReactElement | null

Additional Types

useRender.ComponentProps

type useRenderComponentProps = React.ComponentPropsWithRef<React.ElementType> & {
  render?: ReactElement | ((props: RenderFunctionProps, state: State) => ReactElement);
};

useRender.ElementProps

type useRenderElementProps =
  | (React.PropsWithoutRef<Props> & React.RefAttributes<R | any>)
  | Props
  | React.ComponentProps<React.ElementType>;

useRender.Parameters

type useRenderParameters = {
  render?: UseRenderRenderProp<State>;
  ref?: React.Ref<Element>[] | React.Ref<Element>;
  state?: State;
  stateAttributesMapping?: StateAttributesMapping<State>;
  props?: Record<string, unknown>;
  enabled?: boolean | undefined;
  defaultTagName?:
    | 'symbol'
    | 'object'
    | 'a'
    | 'abbr'
    | 'address'
    | 'area'
    | 'article'
    | 'aside'
    | 'audio'
    | 'b'
    | 'base'
    | 'bdi'
    | 'bdo'
    | 'big'
    | 'blockquote'
    | 'body'
    | 'br'
    | 'button'
    | 'canvas'
    | 'caption'
    | 'center'
    | 'cite'
    | 'code'
    | 'col'
    | 'colgroup'
    | 'data'
    | 'datalist'
    | 'dd'
    | 'del'
    | 'details'
    | 'dfn'
    | 'dialog'
    | 'div'
    | 'dl'
    | 'dt'
    | 'em'
    | 'embed'
    | 'fieldset'
    | 'figcaption'
    | 'figure'
    | 'footer'
    | 'form'
    | 'h1'
    | 'h2'
    | 'h3'
    | 'h4'
    | 'h5'
    | 'h6'
    | 'head'
    | 'header'
    | 'hgroup'
    | 'hr'
    | 'html'
    | 'i'
    | 'iframe'
    | 'img'
    | 'input'
    | 'ins'
    | 'kbd'
    | 'keygen'
    | 'label'
    | 'legend'
    | 'li'
    | 'link'
    | 'main'
    | 'map'
    | 'mark'
    | 'menu'
    | 'menuitem'
    | 'meta'
    | 'meter'
    | 'nav'
    | 'noindex'
    | 'noscript'
    | 'ol'
    | 'optgroup'
    | 'option'
    | 'output'
    | 'p'
    | 'param'
    | 'picture'
    | 'pre'
    | 'progress'
    | 'q'
    | 'rp'
    | 'rt'
    | 'ruby'
    | 's'
    | 'samp'
    | 'search'
    | 'slot'
    | 'script'
    | 'section'
    | 'select'
    | 'small'
    | 'source'
    | 'span'
    | 'strong'
    | 'style'
    | 'sub'
    | 'summary'
    | 'sup'
    | 'table'
    | 'template'
    | 'tbody'
    | 'td'
    | 'textarea'
    | 'tfoot'
    | 'th'
    | 'thead'
    | 'time'
    | 'title'
    | 'tr'
    | 'track'
    | 'u'
    | 'ul'
    | 'var'
    | 'video'
    | 'wbr'
    | 'webview'
    | 'svg'
    | 'animate'
    | 'animateMotion'
    | 'animateTransform'
    | 'circle'
    | 'clipPath'
    | 'defs'
    | 'desc'
    | 'ellipse'
    | 'feBlend'
    | 'feColorMatrix'
    | 'feComponentTransfer'
    | 'feComposite'
    | 'feConvolveMatrix'
    | 'feDiffuseLighting'
    | 'feDisplacementMap'
    | 'feDistantLight'
    | 'feDropShadow'
    | 'feFlood'
    | 'feFuncA'
    | 'feFuncB'
    | 'feFuncG'
    | 'feFuncR'
    | 'feGaussianBlur'
    | 'feImage'
    | 'feMerge'
    | 'feMergeNode'
    | 'feMorphology'
    | 'feOffset'
    | 'fePointLight'
    | 'feSpecularLighting'
    | 'feSpotLight'
    | 'feTile'
    | 'feTurbulence'
    | 'filter'
    | 'foreignObject'
    | 'g'
    | 'image'
    | 'line'
    | 'linearGradient'
    | 'marker'
    | 'mask'
    | 'metadata'
    | 'mpath'
    | 'path'
    | 'pattern'
    | 'polygon'
    | 'polyline'
    | 'radialGradient'
    | 'rect'
    | 'set'
    | 'stop'
    | 'switch'
    | 'text'
    | 'textPath'
    | 'tspan'
    | 'use'
    | 'view';
};

useRender.RenderProp

type useRenderRenderProp =
  | ReactElement
  | ((props: React.HTMLAttributes<any>, state: State) => ReactElement);

useRender.ReturnValue

type useRenderReturnValue = ReactElement | null;

HTMLProps

type HTMLProps = React.HTMLAttributes<T> & { ref?: React.Ref<T> };

UseRenderComponentProps

type UseRenderComponentProps = React.ComponentPropsWithRef<React.ElementType> & {
  render?: ReactElement | ((props: RenderFunctionProps, state: State) => ReactElement);
};

UseRenderElementProps

type UseRenderElementProps =
  | (React.PropsWithoutRef<Props> & React.RefAttributes<R | any>)
  | Props
  | React.ComponentProps<React.ElementType>;

UseRenderParameters

type UseRenderParameters = {
  render?: UseRenderRenderProp<State>;
  ref?: React.Ref<Element> | React.Ref<Element>[];
  state?: State;
  stateAttributesMapping?: StateAttributesMapping<State>;
  props?: Record<string, unknown>;
  enabled?: boolean | undefined;
  defaultTagName?:
    | 'symbol'
    | 'object'
    | 'a'
    | 'abbr'
    | 'address'
    | 'area'
    | 'article'
    | 'aside'
    | 'audio'
    | 'b'
    | 'base'
    | 'bdi'
    | 'bdo'
    | 'big'
    | 'blockquote'
    | 'body'
    | 'br'
    | 'button'
    | 'canvas'
    | 'caption'
    | 'center'
    | 'cite'
    | 'code'
    | 'col'
    | 'colgroup'
    | 'data'
    | 'datalist'
    | 'dd'
    | 'del'
    | 'details'
    | 'dfn'
    | 'dialog'
    | 'div'
    | 'dl'
    | 'dt'
    | 'em'
    | 'embed'
    | 'fieldset'
    | 'figcaption'
    | 'figure'
    | 'footer'
    | 'form'
    | 'h1'
    | 'h2'
    | 'h3'
    | 'h4'
    | 'h5'
    | 'h6'
    | 'head'
    | 'header'
    | 'hgroup'
    | 'hr'
    | 'html'
    | 'i'
    | 'iframe'
    | 'img'
    | 'input'
    | 'ins'
    | 'kbd'
    | 'keygen'
    | 'label'
    | 'legend'
    | 'li'
    | 'link'
    | 'main'
    | 'map'
    | 'mark'
    | 'menu'
    | 'menuitem'
    | 'meta'
    | 'meter'
    | 'nav'
    | 'noindex'
    | 'noscript'
    | 'ol'
    | 'optgroup'
    | 'option'
    | 'output'
    | 'p'
    | 'param'
    | 'picture'
    | 'pre'
    | 'progress'
    | 'q'
    | 'rp'
    | 'rt'
    | 'ruby'
    | 's'
    | 'samp'
    | 'search'
    | 'slot'
    | 'script'
    | 'section'
    | 'select'
    | 'small'
    | 'source'
    | 'span'
    | 'strong'
    | 'style'
    | 'sub'
    | 'summary'
    | 'sup'
    | 'table'
    | 'template'
    | 'tbody'
    | 'td'
    | 'textarea'
    | 'tfoot'
    | 'th'
    | 'thead'
    | 'time'
    | 'title'
    | 'tr'
    | 'track'
    | 'u'
    | 'ul'
    | 'var'
    | 'video'
    | 'wbr'
    | 'webview'
    | 'svg'
    | 'animate'
    | 'animateMotion'
    | 'animateTransform'
    | 'circle'
    | 'clipPath'
    | 'defs'
    | 'desc'
    | 'ellipse'
    | 'feBlend'
    | 'feColorMatrix'
    | 'feComponentTransfer'
    | 'feComposite'
    | 'feConvolveMatrix'
    | 'feDiffuseLighting'
    | 'feDisplacementMap'
    | 'feDistantLight'
    | 'feDropShadow'
    | 'feFlood'
    | 'feFuncA'
    | 'feFuncB'
    | 'feFuncG'
    | 'feFuncR'
    | 'feGaussianBlur'
    | 'feImage'
    | 'feMerge'
    | 'feMergeNode'
    | 'feMorphology'
    | 'feOffset'
    | 'fePointLight'
    | 'feSpecularLighting'
    | 'feSpotLight'
    | 'feTile'
    | 'feTurbulence'
    | 'filter'
    | 'foreignObject'
    | 'g'
    | 'image'
    | 'line'
    | 'linearGradient'
    | 'marker'
    | 'mask'
    | 'metadata'
    | 'mpath'
    | 'path'
    | 'pattern'
    | 'polygon'
    | 'polyline'
    | 'radialGradient'
    | 'rect'
    | 'set'
    | 'stop'
    | 'switch'
    | 'text'
    | 'textPath'
    | 'tspan'
    | 'use'
    | 'view';
};

UseRenderRenderProp

type UseRenderRenderProp =
  | ReactElement
  | ((props: React.HTMLAttributes<any>, state: State) => ReactElement);

UseRenderReturnValue

type UseRenderReturnValue = ReactElement | null;