# useLazyRef
> Creates a ref whose initial value is lazily computed on first render.

Creates a ref whose initial value is lazily computed by a factory function on first render. Unlike `useRef`, the initialiser function is only called once, avoiding unnecessary computation on re-renders.

## Import

```js
import { useLazyRef } from '@volue/wave-react';
```

## Example

> **Tip**
>
> Refs in following example simulate expensive computation by creating a large
> Map. `useLazyRef` skips computation cost after the first render.

```jsx
() => {
  const [, rerender] = React.useState(0);

  // useLazyRef: factory runs only on first render
  const lazyStart = performance.now();
  const lazyRef = useLazyRef(() => {
    return new Map(Array.from({ length: 100000 }, (_, i) => [i, i * i]));
  });
  const lazyTime = (performance.now() - lazyStart).toFixed(2);

  // useRef: the Map is needlessly recreated every render, then discarded
  const refStart = performance.now();
  const regularRef = React.useRef(
    new Map(Array.from({ length: 100000 }, (_, i) => [i, i * i]))
  );
  const refTime = (performance.now() - refStart).toFixed(2);

  return (
    <Flex flow="column" cross="start">
      <Flex flow="column" gap="spacingS">
        <Text>{'useLazyRef: ' + lazyTime + 'ms'}</Text>
        <Text>{'useRef: ' + refTime + 'ms'}</Text>
      </Flex>
      <Button onClick={() => rerender(c => c + 1)}>{'Re-render'}</Button>
    </Flex>
  );
};
```

---

## API reference

### Arguments

| Name       | Type      | Default | Description                                                                  | Required |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------- | -------- |
| `getValue` | `() => T` | `—`     | A function that returns the initial value. Called only once on first render. | Yes      |

### Returns

`RefObject<T>`