React useRef Guide

useRef provides mutable references that persist across renders. Here's how to use it effectively.

Basic useRef#

import { useRef } from 'react';

function TextInput() {
  // Create a ref
  const inputRef = useRef(null);

  const focusInput = () => {
    // Access DOM element
    inputRef.current.focus();
  };

  return (
    <div>
      <input ref={inputRef} type="text" />
      <button onClick={focusInput}>Focus Input</button>
    </div>
  );
}

DOM References#

function VideoPlayer() {
  const videoRef = useRef(null);

  const play = () => videoRef.current.play();
  const pause = () => videoRef.current.pause();

  return (
    <div>
      <video ref={videoRef} src="video.mp4" />
      <button onClick={play}>Play</button>
      <button onClick={pause}>Pause</button>
    </div>
  );
}

// Multiple refs
function Form() {
  const nameRef = useRef(null);
  const emailRef = useRef(null);

  const handleSubmit = () => {
    console.log('Name:', nameRef.current.value);
    console.log('Email:', emailRef.current.value);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input ref={nameRef} name="name" />
      <input ref={emailRef} name="email" type="email" />
      <button type="submit">Submit</button>
    </form>
  );
}

Mutable Values#

function Timer() {
  const [count, setCount] = useState(0);
  const intervalRef = useRef(null);

  const start = () => {
    if (intervalRef.current) return;

    intervalRef.current = setInterval(() => {
      setCount(c => c + 1);
    }, 1000);
  };

  const stop = () => {
    clearInterval(intervalRef.current);
    intervalRef.current = null;
  };

  // Cleanup on unmount
  useEffect(() => {
    return () => clearInterval(intervalRef.current);
  }, []);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
    </div>
  );
}

Previous Value Pattern#

function usePrevious(value) {
  const ref = useRef();

  useEffect(() => {
    ref.current = value;
  }, [value]);

  return ref.current;
}

// Usage
function Counter() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);

  return (
    <div>
      <p>Current: {count}, Previous: {prevCount}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  );
}

Callback Refs#

function MeasuredComponent() {
  const [height, setHeight] = useState(0);

  // Callback ref - called when element mounts/unmounts
  const measuredRef = useCallback(node => {
    if (node !== null) {
      setHeight(node.getBoundingClientRect().height);
    }
  }, []);

  return (
    <div>
      <div ref={measuredRef}>
        Content that might change size
      </div>
      <p>Height: {height}px</p>
    </div>
  );
}

// With ResizeObserver
function ResizableComponent() {
  const [size, setSize] = useState({ width: 0, height: 0 });
  const observerRef = useRef(null);

  const ref = useCallback(node => {
    if (observerRef.current) {
      observerRef.current.disconnect();
    }

    if (node) {
      observerRef.current = new ResizeObserver(entries => {
        const { width, height } = entries[0].contentRect;
        setSize({ width, height });
      });
      observerRef.current.observe(node);
    }
  }, []);

  useEffect(() => {
    return () => observerRef.current?.disconnect();
  }, []);

  return (
    <div ref={ref}>
      Width: {size.width}, Height: {size.height}
    </div>
  );
}

Forwarding Refs#

import { forwardRef, useRef } from 'react';

// Forward ref to child component
const FancyInput = forwardRef((props, ref) => {
  return <input ref={ref} className="fancy" {...props} />;
});

function Parent() {
  const inputRef = useRef(null);

  return (
    <div>
      <FancyInput ref={inputRef} />
      <button onClick={() => inputRef.current.focus()}>
        Focus
      </button>
    </div>
  );
}

// With useImperativeHandle
const CustomInput = forwardRef((props, ref) => {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current.focus(),
    clear: () => { inputRef.current.value = ''; },
    getValue: () => inputRef.current.value,
  }));

  return <input ref={inputRef} {...props} />;
});

function Parent() {
  const inputRef = useRef(null);

  return (
    <div>
      <CustomInput ref={inputRef} />
      <button onClick={() => inputRef.current.focus()}>Focus</button>
      <button onClick={() => inputRef.current.clear()}>Clear</button>
    </div>
  );
}

Avoiding Re-renders#

// useRef doesn't trigger re-renders
function ClickTracker() {
  const clickCount = useRef(0);

  const handleClick = () => {
    clickCount.current += 1;
    console.log(`Clicked ${clickCount.current} times`);
    // No re-render!
  };

  return <button onClick={handleClick}>Click me</button>;
}

// Compare with useState
function ClickTrackerWithState() {
  const [clickCount, setClickCount] = useState(0);

  const handleClick = () => {
    setClickCount(c => c + 1);  // Causes re-render
  };

  return <button onClick={handleClick}>Clicked {clickCount}</button>;
}

// Use ref for values that don't affect UI
function Analytics() {
  const sessionData = useRef({
    pageViews: 0,
    clicks: 0,
    startTime: Date.now()
  });

  const trackClick = () => {
    sessionData.current.clicks++;
    // Update analytics without re-render
  };

  return <button onClick={trackClick}>Track</button>;
}

Latest Value Pattern#

// Access latest value in callbacks
function Chat({ messages, onSend }) {
  const messagesRef = useRef(messages);
  messagesRef.current = messages;

  useEffect(() => {
    const interval = setInterval(() => {
      // Always has latest messages
      console.log('Current messages:', messagesRef.current.length);
    }, 5000);

    return () => clearInterval(interval);
  }, []); // Empty deps, but still gets latest value

  return /* ... */;
}

// Latest callback pattern
function useLatestCallback(callback) {
  const ref = useRef(callback);
  ref.current = callback;

  return useCallback((...args) => {
    return ref.current(...args);
  }, []);
}

function Search({ onSearch }) {
  const latestOnSearch = useLatestCallback(onSearch);

  useEffect(() => {
    // Safe to use in effect without adding to deps
    latestOnSearch('initial');
  }, [latestOnSearch]);
}

Animation Refs#

function AnimatedComponent() {
  const elementRef = useRef(null);
  const animationRef = useRef(null);

  const startAnimation = () => {
    animationRef.current = elementRef.current.animate(
      [
        { transform: 'translateX(0)' },
        { transform: 'translateX(100px)' }
      ],
      { duration: 1000, fill: 'forwards' }
    );
  };

  const stopAnimation = () => {
    animationRef.current?.cancel();
  };

  return (
    <div>
      <div ref={elementRef} className="box" />
      <button onClick={startAnimation}>Animate</button>
      <button onClick={stopAnimation}>Stop</button>
    </div>
  );
}

Scroll Management#

function ScrollToBottom() {
  const bottomRef = useRef(null);
  const containerRef = useRef(null);

  const scrollToBottom = () => {
    bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
  };

  // Auto-scroll on new messages
  useEffect(() => {
    scrollToBottom();
  }, [messages]);

  return (
    <div ref={containerRef} className="chat">
      {messages.map(msg => <Message key={msg.id} {...msg} />)}
      <div ref={bottomRef} />
    </div>
  );
}

// Save and restore scroll position
function ScrollRestoration({ items }) {
  const containerRef = useRef(null);
  const scrollPosRef = useRef(0);

  const saveScroll = () => {
    scrollPosRef.current = containerRef.current.scrollTop;
  };

  const restoreScroll = () => {
    containerRef.current.scrollTop = scrollPosRef.current;
  };

  return (
    <div
      ref={containerRef}
      onScroll={saveScroll}
    >
      {items.map(/* ... */)}
    </div>
  );
}

TypeScript#

// Typed refs
const inputRef = useRef<HTMLInputElement>(null);
const divRef = useRef<HTMLDivElement>(null);

// Mutable ref with initial value
const countRef = useRef<number>(0);
countRef.current = 5;  // OK

// Nullable ref
const elementRef = useRef<HTMLElement | null>(null);

// Forward ref with types
interface InputProps {
  label: string;
}

const Input = forwardRef<HTMLInputElement, InputProps>(
  ({ label }, ref) => (
    <label>
      {label}
      <input ref={ref} />
    </label>
  )
);

Best Practices#

Use ref for:
✓ DOM element access
✓ Mutable values without re-render
✓ Timer/animation IDs
✓ Previous values

Patterns:
✓ useCallback for measurement refs
✓ forwardRef for component refs
✓ useImperativeHandle for custom API
✓ Cleanup in useEffect

Avoid:
✗ Reading ref.current during render
✗ Using ref for render-dependent data
✗ Overusing refs instead of state
✗ Forgetting null checks

Performance:
✓ Track values without re-renders
✓ Store computed values
✓ Cache DOM measurements
✓ Hold instance variables

useRef provides persistent mutable values across renders. Use it for DOM access, storing values that don't affect rendering, tracking previous state, and holding timer/animation IDs. Unlike state, updating refs doesn't trigger re-renders. Remember that refs are null initially when used for DOM elements, so always check before accessing.