> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/preactjs/preact/llms.txt
> Use this file to discover all available pages before exploring further.

# createRef

> Create a ref object for accessing DOM nodes or component instances

Creates a mutable ref object that can hold a reference to a DOM node or component instance.

## Signature

```typescript theme={null}
function createRef<T = any>(): RefObject<T>
```

## Type Parameters

<ParamField path="T" type="any" default="any">
  The type of the value the ref will hold (e.g., `HTMLDivElement`, `HTMLInputElement`).
</ParamField>

## Return Value

Returns a `RefObject<T>` with the following structure:

```typescript theme={null}
interface RefObject<T> {
  current: T | null;
}
```

The `current` property:

* Initially set to `null`
* Updated by Preact when the component mounts
* Set to the DOM node or component instance
* Reset to `null` when the component unmounts

## Description

`createRef` creates a mutable object whose `current` property is initialized to `null`. This object persists for the lifetime of the component and is used to access DOM nodes or component instances directly.

Refs are useful for:

* Managing focus, text selection, or media playback
* Triggering imperative animations
* Integrating with third-party DOM libraries
* Accessing component methods

## Implementation

The function is implemented in `src/create-element.js:73`:

```javascript theme={null}
export function createRef() {
  return { current: NULL };
}
```

The implementation is simple - it returns a plain object with a `current` property initialized to `null`.

## Usage Examples

### Accessing DOM Elements

```jsx theme={null}
import { createRef, Component } from 'preact';

class AutoFocusInput extends Component {
  inputRef = createRef();
  
  componentDidMount() {
    // Focus the input after mount
    this.inputRef.current.focus();
  }
  
  render() {
    return <input ref={this.inputRef} type="text" />;
  }
}
```

### With Function Components

```jsx theme={null}
import { createRef } from 'preact';
import { useEffect } from 'preact/hooks';

function VideoPlayer() {
  const videoRef = createRef();
  
  useEffect(() => {
    // Play video on mount
    videoRef.current.play();
  }, []);
  
  const handlePause = () => {
    videoRef.current.pause();
  };
  
  return (
    <div>
      <video ref={videoRef} src="video.mp4" />
      <button onClick={handlePause}>Pause</button>
    </div>
  );
}
```

### Measuring DOM Elements

```jsx theme={null}
import { createRef, Component } from 'preact';

class MeasureDiv extends Component {
  divRef = createRef();
  
  measureElement = () => {
    const element = this.divRef.current;
    console.log('Width:', element.offsetWidth);
    console.log('Height:', element.offsetHeight);
    console.log('Position:', element.getBoundingClientRect());
  }
  
  render() {
    return (
      <div>
        <div ref={this.divRef} style={{ width: '200px', height: '100px' }}>
          Measure me!
        </div>
        <button onClick={this.measureElement}>Get Measurements</button>
      </div>
    );
  }
}
```

### Managing Focus

```jsx theme={null}
import { createRef, Component } from 'preact';

class Form extends Component {
  nameRef = createRef();
  emailRef = createRef();
  
  handleNameSubmit = (e) => {
    e.preventDefault();
    // Move focus to email field
    this.emailRef.current.focus();
  }
  
  render() {
    return (
      <form>
        <input
          ref={this.nameRef}
          placeholder="Name"
          onKeyPress={(e) => e.key === 'Enter' && this.handleNameSubmit(e)}
        />
        <input
          ref={this.emailRef}
          type="email"
          placeholder="Email"
        />
      </form>
    );
  }
}
```

### With TypeScript

```tsx theme={null}
import { createRef, Component } from 'preact';

class TypedInput extends Component {
  // Specify the element type
  inputRef = createRef<HTMLInputElement>();
  buttonRef = createRef<HTMLButtonElement>();
  
  componentDidMount() {
    // TypeScript knows inputRef.current is HTMLInputElement | null
    this.inputRef.current?.focus();
    
    // Access type-specific properties
    const value = this.inputRef.current?.value;
    const isDisabled = this.buttonRef.current?.disabled;
  }
  
  render() {
    return (
      <div>
        <input ref={this.inputRef} />
        <button ref={this.buttonRef}>Submit</button>
      </div>
    );
  }
}
```

### Text Selection

```jsx theme={null}
import { createRef, Component } from 'preact';

class SelectableText extends Component {
  textRef = createRef();
  
  selectAll = () => {
    const input = this.textRef.current;
    input.select();
  }
  
  selectRange = (start, end) => {
    const input = this.textRef.current;
    input.setSelectionRange(start, end);
    input.focus();
  }
  
  render() {
    return (
      <div>
        <input
          ref={this.textRef}
          type="text"
          defaultValue="Select this text"
        />
        <button onClick={this.selectAll}>Select All</button>
        <button onClick={() => this.selectRange(0, 6)}>Select First Word</button>
      </div>
    );
  }
}
```

### Integrating Third-Party Libraries

```jsx theme={null}
import { createRef, Component } from 'preact';
import * as d3 from 'd3';

class D3Chart extends Component {
  svgRef = createRef();
  
  componentDidMount() {
    // Use D3 with the DOM element
    const svg = d3.select(this.svgRef.current);
    svg.append('circle')
      .attr('cx', 50)
      .attr('cy', 50)
      .attr('r', 40)
      .attr('fill', 'blue');
  }
  
  render() {
    return <svg ref={this.svgRef} width="100" height="100" />;
  }
}
```

### Multiple Refs

```jsx theme={null}
import { createRef, Component } from 'preact';

class MultipleRefs extends Component {
  firstRef = createRef();
  secondRef = createRef();
  thirdRef = createRef();
  
  focusNext = (currentRef, nextRef) => {
    const current = currentRef.current;
    if (current.value.length >= current.maxLength) {
      nextRef.current.focus();
    }
  }
  
  render() {
    return (
      <div>
        <input
          ref={this.firstRef}
          maxLength={3}
          onChange={() => this.focusNext(this.firstRef, this.secondRef)}
        />
        <input
          ref={this.secondRef}
          maxLength={3}
          onChange={() => this.focusNext(this.secondRef, this.thirdRef)}
        />
        <input ref={this.thirdRef} maxLength={3} />
      </div>
    );
  }
}
```

### Forwarding Refs

```jsx theme={null}
import { createRef, forwardRef } from 'preact';

// Component that forwards its ref to an internal element
const FancyInput = forwardRef((props, ref) => (
  <div className="fancy-input">
    <input ref={ref} {...props} />
  </div>
));

function Parent() {
  const inputRef = createRef();
  
  const focusInput = () => {
    inputRef.current.focus();
  };
  
  return (
    <div>
      <FancyInput ref={inputRef} placeholder="Forwarded ref" />
      <button onClick={focusInput}>Focus Input</button>
    </div>
  );
}
```

## Ref vs useRef Hook

For function components, prefer the `useRef` hook:

```jsx theme={null}
// Class component - use createRef
import { createRef, Component } from 'preact';

class MyClass extends Component {
  myRef = createRef();
  
  render() {
    return <div ref={this.myRef} />;
  }
}

// Function component - use useRef
import { useRef } from 'preact/hooks';

function MyFunction() {
  const myRef = useRef(null);
  
  return <div ref={myRef} />;
}
```

**Key differences:**

* `createRef` creates a new object every time
* `useRef` persists the same object across re-renders
* `useRef` is preferred for function components

## Common Patterns

### Conditional Refs

```jsx theme={null}
import { createRef, Component } from 'preact';

class ConditionalRef extends Component {
  inputRef = createRef();
  
  componentDidUpdate(prevProps) {
    if (this.props.shouldFocus && !prevProps.shouldFocus) {
      this.inputRef.current?.focus();
    }
  }
  
  render() {
    return (
      <input
        ref={this.inputRef}
        type="text"
        placeholder="Type here"
      />
    );
  }
}
```

### Callback Refs

For more control, use callback refs instead:

```jsx theme={null}
import { Component } from 'preact';

class CallbackRefExample extends Component {
  setInputRef = (element) => {
    this.inputElement = element;
    if (element) {
      element.focus();
    }
  }
  
  render() {
    return <input ref={this.setInputRef} />;
  }
}
```

## Best Practices

1. **Check for null**: Always check if `ref.current` exists before using it

```jsx theme={null}
if (this.myRef.current) {
  this.myRef.current.focus();
}

// Or use optional chaining
this.myRef.current?.focus();
```

2. **Don't overuse refs**: Use refs only when necessary. For most cases, data flow through props is preferred

3. **Avoid string refs**: Preact supports string refs for compatibility, but object refs are preferred

```jsx theme={null}
// ❌ Avoid string refs
<input ref="myInput" />

// ✅ Use object refs
<input ref={this.myRef} />
```

4. **Function components**: Use `useRef` hook instead of `createRef` in function components

## Related APIs

* `useRef` hook - Ref hook for function components
* `forwardRef` - Forward refs through components
* [`Component`](/api/component) - Class component API
* [`h`](/api/h) - Create elements with refs