---
title: useMediaAttach
description: Hook to register a custom media element with the player context
---

import UtilReference from "@/components/docs/api-reference/UtilReference.astro";

`useMediaAttach` returns a setter function for attaching a media element to the player context. The built-in `<Video>` and `<Audio>` components use this internally -- you only need it when building a custom media element.

```tsx title="CustomMedia.tsx"
import { useMediaAttach } from "@videojs/react";

function CustomMedia({ src }: { src: string }) {
  const setMedia = useMediaAttach();
  return <video ref={setMedia} src={src} />;
}
```

## Who needs this

You only need `useMediaAttach` if you're replacing the built-in `<Video>` or `<Audio>` components with a custom element. For example, if you're...

- Wrapping a third-party video player
- Using a `<canvas>` or WebGL-based renderer
- Building a custom `<audio>` element with additional markup

For standard `<video>` and `<audio>` playback, use the built-in components.

## Safe outside Provider

Returns `undefined` when called outside a Player `Provider`. Check the return value before using it -- this avoids crashes in components that may render outside the player tree.

<UtilReference util="useMediaAttach" />
