Refs

Refs provide a way to access DOM nodes or Preact elements created in the render method. They’re also useful for storing mutable values that persist across renders without causing re-renders.

When to Use Refs

Refs are useful for:

Managing focus, text selection, or media playback
Triggering imperative animations
Integrating with third-party DOM libraries
Storing values that don’t affect rendering

Don’t overuse refs. Most things should be done declaratively with props and state.

Creating Refs

Preact provides two ways to create refs:

useRef Hook (Recommended)
createRef

The useRef hook is the recommended way to create refs in function components:

import { useRef } from 'preact/hooks';

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

  const focusInput = () => {
    inputRef.current.focus();
  };

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

How useRef Works

The useRef hook is implemented in hooks/src/index.js as a simple wrapper around useMemo:

// From hooks/src/index.js:306-309
export function useRef(initialValue) {
  currentHook = 5;
  return useMemo(() => ({ current: initialValue }), []);
}

It returns an object with a current property that persists across renders.Reference: hooks/src/index.js:306-309

For class components or when you need to create a ref outside of a component, use createRef:

import { Component, createRef } from 'preact';

class TextInput extends Component {
  inputRef = createRef();

  focusInput = () => {
    this.inputRef.current.focus();
  };

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

createRef Implementation

The createRef function is simple - it just returns an object:

// From src/create-element.js:73-75
export function createRef() {
  return { current: null };
}

Reference: src/create-element.js:73-75

Accessing DOM Elements

The most common use of refs is to access DOM elements directly:

import { useRef, useEffect } from 'preact/hooks';

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

  useEffect(() => {
    // Focus input on mount
    inputRef.current.focus();
  }, []);

  return <input ref={inputRef} placeholder="Search..." />;
}

Callback Refs

Instead of passing a ref object, you can pass a function. Preact will call it with the DOM element:

import { useState } from 'preact/hooks';

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

  const measuredRef = element => {
    if (element) {
      setHeight(element.getBoundingClientRect().height);
    }
  };

  return (
    <div>
      <div ref={measuredRef}>
        <p>This element's height is: {height}px</p>
      </div>
    </div>
  );
}

Callback refs are called with null when the component unmounts. Always check if the element exists.

Storing Mutable Values

Refs aren’t just for DOM elements. They’re perfect for storing values that need to persist across renders but shouldn’t trigger re-renders when changed:

import { useRef, useState, useEffect } from 'preact/hooks';

function Stopwatch() {
  const [time, setTime] = useState(0);
  const intervalRef = useRef(null);

  const start = () => {
    if (intervalRef.current) return; // Already running
    
    intervalRef.current = setInterval(() => {
      setTime(t => t + 1);
    }, 1000);
  };

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

  const reset = () => {
    stop();
    setTime(0);
  };

  useEffect(() => {
    return () => stop(); // Cleanup on unmount
  }, []);

  return (
    <div>
      <div>Time: {time}s</div>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Forwarding Refs

Sometimes you need to pass a ref through a component to one of its children. Use forwardRef from preact/compat:

Basic Ref Forwarding

import { forwardRef } from 'preact/compat';

const FancyInput = forwardRef((props, ref) => (
  <div className="fancy-input">
    <input ref={ref} {...props} />
  </div>
));

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

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

With useImperativeHandle

Customize what the ref exposes using useImperativeHandle:

import { forwardRef } from 'preact/compat';
import { useRef, useImperativeHandle } from 'preact/hooks';

const VideoPlayer = forwardRef((props, ref) => {
  const videoRef = useRef(null);

  useImperativeHandle(ref, () => ({
    play: () => videoRef.current.play(),
    pause: () => videoRef.current.pause(),
    restart: () => {
      videoRef.current.currentTime = 0;
      videoRef.current.play();
    }
  }));

  return <video ref={videoRef} src={props.src} />;
});

// Usage
function Parent() {
  const playerRef = useRef(null);

  return (
    <div>
      <VideoPlayer ref={playerRef} src="video.mp4" />
      <button onClick={() => playerRef.current.play()}>Play</button>
      <button onClick={() => playerRef.current.pause()}>Pause</button>
      <button onClick={() => playerRef.current.restart()}>Restart</button>
    </div>
  );
}

Implementation Details

The forwardRef function is implemented in compat/src/forwardRef.js:

// From compat/src/forwardRef.js:12-31
export function forwardRef(fn) {
  function Forwarded(props) {
    let clone = assign({}, props);
    delete clone.ref;
    return fn(clone, props.ref || null);
  }

  Forwarded.$$typeof = Symbol.for('react.forward_ref');
  Forwarded.render = fn;
  Forwarded.prototype.isReactComponent = true;
  Forwarded.displayName = 'ForwardRef(' + (fn.displayName || fn.name) + ')';

  return Forwarded;
}

Reference: compat/src/forwardRef.js:12-31

Ref Best Practices

Check for null

Always check if the ref exists before accessing it:

function Component() {
  const ref = useRef(null);

  const handleClick = () => {
    // Good: Check before accessing
    if (ref.current) {
      ref.current.focus();
    }
  };

  return <input ref={ref} />;
}

Don’t access refs during render

Refs should be accessed in event handlers or effects, not during render:

function Component() {
  const ref = useRef(null);

  // Bad: Accessing during render
  const width = ref.current?.offsetWidth;

  // Good: Access in effect
  useEffect(() => {
    const width = ref.current?.offsetWidth;
    console.log(width);
  }, []);

  return <div ref={ref}>Content</div>;
}

Use refs sparingly

Most things should be done declaratively. Only use refs when necessary:

// Bad: Using ref for something that should be state
function Component() {
  const countRef = useRef(0);
  
  return (
    <button onClick={() => countRef.current++}>
      Count: {countRef.current} {/* Won't update! */}
    </button>
  );
}

// Good: Use state for values that affect rendering
function Component() {
  const [count, setCount] = useState(0);
  
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

Clean up in effects

When using refs with effects, clean up properly:

function Component() {
  const ref = useRef(null);

  useEffect(() => {
    const element = ref.current;
    if (!element) return;

    const observer = new ResizeObserver(() => {
      console.log('Resized');
    });

    observer.observe(element);

    return () => {
      observer.unobserve(element);
    };
  }, []);

  return <div ref={ref}>Content</div>;
}

Common Patterns

import { useRef, useEffect } from 'preact/hooks';

function AutoFocusInput({ autoFocus, ...props }) {
  const ref = useRef(null);

  useEffect(() => {
    if (autoFocus && ref.current) {
      ref.current.focus();
    }
  }, [autoFocus]);

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

Getting Started

Core Concepts

Guides

React Compatibility

Advanced

When to Use Refs

Creating Refs

How useRef Works

createRef Implementation

Accessing DOM Elements

Callback Refs

Storing Mutable Values

Forwarding Refs

Ref Best Practices

Common Patterns

Next Steps

Hooks

Fragments

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

React Compatibility

Advanced

​When to Use Refs

​Creating Refs

​How useRef Works

​createRef Implementation

​Accessing DOM Elements

​Callback Refs

​Storing Mutable Values

​Forwarding Refs

​Ref Best Practices

​Common Patterns

​Next Steps

Hooks

Fragments

Build docs developers (and LLMs) love

When to Use Refs

Creating Refs

How useRef Works

createRef Implementation

Accessing DOM Elements

Callback Refs

Storing Mutable Values

Forwarding Refs

Ref Best Practices

Common Patterns

Next Steps