useMergeRefs

@coinbase/cds-common@8.13.6

Combines multiple refs into a single ref callback, allowing a component to work with multiple ref instances simultaneously. Useful when you need to combine refs from different sources, such as forwarded refs and internal component state.

Import

import { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs'

SourceView source code

---

Basic usage

Loading...

󰙡

Live Code

function Example() {
  // Create an internal ref for component logic
  const internalRef = useRef<HTMLDivElement>(null);

  // Simulating a forwarded ref from parent
  const Component = forwardRef((props, forwardedRef) => {
    // Merge the internal ref with the forwarded ref
    const refs = useMergeRefs(forwardedRef, internalRef);

    return (
      <Box ref={refs} padding={3} background="bgAlternate" borderRadius={300}>
        <TextBody>This box uses a merged ref</TextBody>
      </Box>
    );
  });

  return <Component />;
}

---

With Multiple Refs

Loading...

󰙡

Live Code

function Example() {
  const firstRef = useRef<HTMLDivElement>(null);
  const secondRef = useRef<HTMLDivElement>(null);
  const thirdRef = useRef<HTMLDivElement>(null);

  // Function to check if all refs are properly set
  const checkRefs = () => {
    const allRefsSet = firstRef.current && secondRef.current && thirdRef.current;
    alert(`All refs are ${allRefsSet ? 'set' : 'not set'}`);
  };

  // Merge all three refs
  const mergedRefs = useMergeRefs(firstRef, secondRef, thirdRef);

  return (
    <VStack gap={2}>
      <Box ref={mergedRefs} padding={3} background="bgAlternate" borderRadius={300}>
        <TextBody>This element is referenced by three refs</TextBody>
      </Box>
      <Button onClick={checkRefs}>Check Refs</Button>
    </VStack>
  );
}

---

With Function Ref

Loading...

󰙡

Live Code

function Example() {
  const [elementWidth, setElementWidth] = useState<number>(0);

  // Create a function ref that measures the element
  const functionRef = (element: HTMLDivElement | null) => {
    if (element) {
      setElementWidth(element.offsetWidth);
    }
  };

  // Create an object ref for other purposes
  const objectRef = useRef<HTMLDivElement>(null);

  // Merge both types of refs
  const refs = useMergeRefs(functionRef, objectRef);

  return (
    <VStack gap={2}>
      <Box ref={refs} padding={3} background="bgAlternate" borderRadius={300} width="100%">
        <TextBody>This box uses both function and object refs</TextBody>
      </Box>
      <TextBody>Box width: {elementWidth}px</TextBody>
    </VStack>
  );
}