Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jerricho93 merged 2 commits into from
Jun 18, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8c447e2
docs(react): clarify usePlayer typed vs untyped store access
Jerricho93 Jun 5, 2026
3a5b740
docs(site): fold usePlayer typed/untyped note into prose
Jerricho93 Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions packages/react/src/player/context.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,12 +45,20 @@ export function usePlayerContext(): PlayerContextValue {
/**
* Access the player store from within a Player Provider.
*
* This standalone hook has no knowledge of your configured features, so it
* returns an untyped `UnknownStore` whose state properties are typed as
* `unknown`. For typed access, use the `usePlayer` returned by `createPlayer()`,
* or pass a premade selector to recover the type from its return value.
*
* @label Without Selector
*/
export function usePlayer(): UnknownStore;
/**
* Select a value from the player store. Re-renders when the selected value changes.
*
* The selector receives `UnknownState`, so an inline selector returns `unknown`.
* Pass a premade selector (e.g. `selectPlayback`) to get a typed result.
*
* @label With Selector
* @param selector - Derives a value from the player store state.
*/
Expand Down
11 changes: 10 additions & 1 deletion site/src/content/docs/reference/use-player.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,16 @@ import SelectorDemoReact from "@/components/docs/demos/use-player/react/css/Sele
import selectorReactTsx from "@/components/docs/demos/use-player/react/css/Selector.tsx?raw";
import selectorReactCss from "@/components/docs/demos/use-player/react/css/Selector.css?raw";

`Player.usePlayer` gives you access to the player store from any component within a `Player.Provider`. It has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions. `Player.usePlayer` is typed to the features you passed to <DocsLink slug="reference/create-player">`createPlayer`</DocsLink>. It's also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped store.
`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`, and has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions.

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

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

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

@decepulis decepulis Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  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 Jerricho93 Jun 15, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Examples

Expand Down
Loading