docs(react): clarify usePlayer typed vs untyped store access

[Jerricho93]

Closes #1483

Summary

The use-player reference page mentioned the typed-vs-untyped distinction only in a single easy-to-miss sentence, so users assumed the standalone usePlayer() is supposed to return unknown. This makes the distinction prominent on the page and corrects the standalone hook's generated reference.

Changes

• Add a note callout to the use-player reference page: Player.usePlayer (from createPlayer) is typed to the configured features and needs no selector, while the standalone import { usePlayer } returns an untyped UnknownStore and needs a premade selector to recover typing.
• Enrich the standalone usePlayer JSDoc so the generated reference explains the UnknownStore return — and that inline selectors stay unknown while premade selectors (e.g. selectPlayback) carry their type.

Testing

• pnpm -F site api-docs — regenerates the util reference; confirmed use-player.json now includes the new JSDoc paragraphs.
• pnpm build:site — site builds and the page renders.

Related: #1111 (premade selectors incompatible with createPlayer().PlayerController types) is a separate types bug and is not addressed here.

---

Note

Low Risk
Documentation and JSDoc only; no runtime or type behavior changes.

Overview
Improves discoverability of typed vs. untyped usePlayer behavior so users don’t treat standalone unknown returns as a bug.

The use-player reference adds a note callout and a short example: Player.usePlayer from createPlayer() is feature-typed without a selector; standalone import { usePlayer } from '@videojs/react' yields an UnknownStore, with typing recoverable via premade selectors like selectPlayback.

JSDoc on the standalone usePlayer overloads now states the same — no feature knowledge, UnknownStore / UnknownState, inline selectors stay unknown, premade selectors carry their return type — so generated API reference matches the docs page.

^{Reviewed by Cursor Bugbot for commit 8c447e2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[netlify]

👷 Deploy request for vjs10-site pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	3a5b740

[vercel]

@Jerricho93 is attempting to deploy a commit to the Mux Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v10-sandbox	Ready	Preview, Comment	Jun 15, 2026 8:23pm

[decepulis]

Close. One blocking comment (we don't want to tell folks about @videojs/core) and two suggestions to tighten up the copy a bit

[decepulis]

1. blocking: we try not to expose @videojs/core. Luckily, @videojs/react re-exports the important bits.
2. suggestion: I wonder if we need the aside. The code block feels visually-prominent enough.
3. suggestion: The aside feels redundant with some of what comes above it. Maybe we can combine the two... something like this?

What do you think of a change like this?

`Player.usePlayer` (from <DocsLink slug="reference/create-player">`createPlayer`</DocsLink>) gives you access to the player store from any component within a `Player.Provider`. It's typed to the features you passed to `createPlayer`. It has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions.

`usePlayer` also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an `UnknownStore`. Pass a premade selector to recover typing:

```tsx
import { usePlayer, selectPlayback } from '@videojs/react';

usePlayer();               // UnknownStore (state: unknown)
usePlayer(selectPlayback); // PlaybackState | undefined
```

[Jerricho93]

This looks great! I'll push the changes right now. Will change the blocking one, and apply both suggestions, since they help understand cleanly what we want to inform the users

[decepulis]

Excellent. Thank you!