mergeProps

A utility to merge multiple sets of React props.

mergeProps helps you combine multiple prop objects (for example, internal props + user props) into a single set of props you can spread onto an element. It behaves like Object.assign (rightmost wins) with a few special cases, so common React patterns work as expected.

How merging works

For most keys (everything except className, style, and event handlers), the value from the rightmost object wins:
returns { id: 'b', dir: 'ltr' }
```
mergeProps({ id: 'a', dir: 'ltr' }, { id: 'b' });
```
ref is not merged. Only the rightmost ref is kept:
only refB is used
```
mergeProps({ ref: refA }, { ref: refB });
```
className values are concatenated right-to-left (rightmost first):
className is 'b a'
```
mergeProps({ className: 'a' }, { className: 'b' });
```
style objects are merged, with keys from the rightmost style overwriting earlier ones.
Event handlers are merged and executed right-to-left (rightmost first):
b runs before a
```
mergeProps({ onClick: a }, { onClick: b });
```
- For React synthetic events, Base UI adds event.preventBaseUIHandler(). Calling it prevents Base UI’s internal logic from running. This does not call preventDefault() or stopPropagation().
- For non-synthetic events (custom events with primitive/object values), this mechanism isn’t available and all handlers always execute.

Preventing Base UI’s default behavior

When using the function form of the render prop, props are not merged automatically. You can use mergeProps to combine Base UI’s props with your own, and call preventBaseUIHandler() to stop Base UI’s internal logic from running:

Favorite (locked)

index.tsx index.module.css theme.css

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

export default function ExamplePreventBaseUIHandler() {
  const [locked, setLocked] = React.useState(true);
  const [pressed, setPressed] = React.useState(true);
  const getToggleProps = (props: React.ComponentProps<'button'>) =>
    mergeProps<'button'>(props, {
      onClick(event) {
        if (locked) {
          event.preventBaseUIHandler();
        }
      },
    });

  return (
    <div className={styles.Container}>
      <div className={styles.ToggleRow}>
        <div className={styles.Panel}>
          <Toggle
            aria-label="Favorite"
            pressed={pressed}
            onPressedChange={setPressed}
            className={styles.Button}
            render={(props, state) => (
              <button type="button" {...getToggleProps(props)}>
                {state.pressed ? (
                  <HeartFilledIcon className={styles.Icon} />
                ) : (
                  <HeartOutlineIcon className={styles.Icon} />
                )}
              </button>
            )}
          />
        </div>
        <span className={styles.Label}>Favorite {locked ? '(locked)' : '(unlocked)'}</span>
      </div>
      <button type="button" className={styles.LockButton} onClick={() => setLocked((l) => !l)}>
        {locked ? 'Unlock' : 'Lock'}
      </button>
    </div>
  );
}

function HeartFilledIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="currentcolor" {...props}>
      <path d="M7.99961 13.8667C7.88761 13.8667 7.77561 13.8315 7.68121 13.7611C7.43321 13.5766 1.59961 9.1963 1.59961 5.8667C1.59961 3.80856 3.27481 2.13336 5.33294 2.13336C6.59054 2.13336 7.49934 2.81176 7.99961 3.3131C8.49988 2.81176 9.40868 2.13336 10.6663 2.13336C12.7244 2.13336 14.3996 3.80803 14.3996 5.8667C14.3996 9.1963 8.56601 13.5766 8.31801 13.7616C8.22361 13.8315 8.11161 13.8667 7.99961 13.8667Z" />
    </svg>
  );
}

function HeartOutlineIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="currentcolor" {...props}>
      <path
        fillRule="evenodd"
        clipRule="evenodd"
        d="M7.99961 4.8232L7.24456 4.06654C6.84123 3.66235 6.18866 3.20003 5.33294 3.20003C3.86391 3.20003 2.66628 4.39767 2.66628 5.8667C2.66628 6.4079 2.91276 7.1023 3.41967 7.91383C3.91548 8.70759 4.59649 9.51244 5.31278 10.2503C6.38267 11.3525 7.47318 12.2465 7.99983 12.6605C8.52734 12.2456 9.61718 11.352 10.6864 10.2504C11.4027 9.51248 12.0837 8.70762 12.5796 7.91384C13.0865 7.1023 13.3329 6.4079 13.3329 5.8667C13.3329 4.39723 12.1354 3.20003 10.6663 3.20003C9.81056 3.20003 9.15799 3.66235 8.75466 4.06654L7.99961 4.8232ZM7.98574 3.29926C7.48264 2.79938 6.57901 2.13336 5.33294 2.13336C3.27481 2.13336 1.59961 3.80856 1.59961 5.8667C1.59961 9.1963 7.43321 13.5766 7.68121 13.7611C7.77561 13.8315 7.88761 13.8667 7.99961 13.8667C8.11161 13.8667 8.22361 13.8315 8.31801 13.7616C8.56601 13.5766 14.3996 9.1963 14.3996 5.8667C14.3996 3.80803 12.7244 2.13336 10.6663 2.13336C9.42013 2.13336 8.51645 2.79947 8.01337 3.29936C8.00877 3.30393 8.00421 3.30849 7.99967 3.31303C7.99965 3.31305 7.99963 3.31307 7.99961 3.3131C7.99502 3.3085 7.9904 3.30389 7.98574 3.29926Z"
      />
    </svg>
  );
}

Passing a function instead of an object

Each argument can be a props object or a function that receives the merged props up to that point (left to right) and returns a props object. This is useful when you need to compute the next props from whatever has already been merged.

Note that the function’s return value completely replaces the accumulated props up to that point. If you want to chain event handlers from the previous props, you must call them manually:

Manually chaining handlers in a function

const merged = mergeProps(
  {
    onClick(event) {
      // Handler from previous props
    },
  },
  (props) => ({
    onClick(event) {
      // Manually call the previous handler
      props.onClick?.(event);
      // Your logic here
    },
  }),
);

API reference

mergeProps

This function accepts up to 5 arguments, each being either a props object or a function that returns a props object. If you need to merge more than 5 sets of props, use mergePropsN instead.

Parameters

a^*InputProps<ElementType>—

Name: a
Description: Props object to merge.
Type: InputProps<ElementType>

b^*InputProps<ElementType>—

Name: b
Description: Props object to merge. The function will overwrite conflicting props from a.
Type: InputProps<ElementType>

cInputProps<ElementType>—

Name: c
Description: Props object to merge. The function will overwrite conflicting props from previous parameters.
Type: InputProps<ElementType>

dInputProps<ElementType>—

Name: d
Description: Props object to merge. The function will overwrite conflicting props from previous parameters.
Type: InputProps<ElementType>

eInputProps<ElementType>—

Name: e
Description: Props object to merge. The function will overwrite conflicting props from previous parameters.
Type: InputProps<ElementType>

Return value

{}

The merged props.

Type	Description
`{}`	The merged props.

mergePropsN

This function accepts an array of props objects or functions that return props objects. It is slightly less efficient than mergeProps, so only use it when you need to merge more than 5 sets of props.

Parameters

props^*InputProps<ElementType>[]—

Name: props
Description: Array of props to merge.
Type: InputProps<ElementType>[]

Return value

{}

The merged props.