The current useVideoPlayer hook is designed for managing a single video player instance. While handling static, single video instances is straightforward, rendering and managing dynamic lists of videos is currently difficult.

In applications like social media feeds or dynamic content lists, developers often need to:

Render a large, dynamic array of videos.

Manage the player instances for only the videos currently in the viewport (or near it) for optimization (e.g., preloading).

Current Anti-Pattern

Due to the lack of a dedicated multi-player hook, developers are forced to use a component wrapper to dynamically instantiate useVideoPlayer based on the list rendering, which leads to a violation of React's Hooks rules.

This approach is an anti-pattern because it violates the "Rules of Hooks" by dynamically calling a hook inside a component that is itself dynamically rendered, leading to unstable hook calls (as noted in the React documentation: Don’t dynamically mutate a Hook).

Example of the bad pattern:

function App() {

// ...

// fetching video data

return (

<>

{data.videos.map(({ source }) => (

<InitializeVideoPlayerWithPreload key={source} source={source} />

))}

</>

);

}

function InitializeVideoPlayerWithPreload({ source }) {

// Use of an external state store (Zustand, Redux, etc.) to store player instances

const { addVideoPlayer, removeVideoPlayer } = useVideoPlayerStore();

// This hook is called dynamically inside a component rendered by map()

const player = useVideoPlayer(source);

useEffect(() => {

addVideoPlayer({ source, player });

return () => {

removeVideoPlayer(source);

};

}, []);

return null;

}

Therefore, I propose introducing a new hook, tentatively named useMultiVideoPlayer (or useVideoPlayers), to manage multiple instances correctly at the top level of a component.

Desired API

The hook would accept an array of video sources and return an object map of the managed players, ensuring the number of hook calls remains stable.

const players = useMultiVideoPlayer(sources: VideoSource[]);

// players would be: { [sourceUri: string]: VideoPlayer }

This pattern would allow developers to safely generate and manage a dynamic set of player instances within a stable component context.

If this feature is approved, I would like to contribute the implementation and open a Pull Request.