Refs

Access DOM nodes and persist values across renders

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)

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

createRef

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:

Focus Management

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:

Timers

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:

Ref Best Practices

Common Patterns

Auto-focus

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} />;
}

Next Steps

Hooks

Learn about useRef and other hooks in depth

Fragments

Return multiple elements without wrapper nodes