docs(site): add how-to guide for building custom components#1008
docs(site): add how-to guide for building custom components#1008
Conversation
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📦 Bundle Size Report🎨 @videojs/html — no changesPresets (7)
Media (8)
Players (3)
Skins (29)
UI Components (25)
Sizes are marginal over the root entry point. ⚛️ @videojs/react — no changesPresets (7)
Media (7)
Skins (26)
UI Components (20)
Sizes are marginal over the root entry point. 🧩 @videojs/core — no changesEntries (9)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (10)
📦 @videojs/spf — no changesEntries (3)
ℹ️ How to interpretAll sizes are standalone totals (minified + brotli).
Run |
There was a problem hiding this comment.
Pull request overview
Adds a new “Build your own component” how-to guide to the docs site, aimed at helping users create custom player controls that read state, dispatch actions, and remain accessible.
Changes:
- Added a new how-to guide at
how-to/build-your-own-component.mdxwith React + HTML framework examples (including a “skip intro” control). - Added the new guide to the “How to” section of the docs sidebar.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
site/src/docs.config.ts |
Adds the new how-to page slug to the “How to” sidebar contents. |
site/src/content/docs/how-to/build-your-own-component.mdx |
Introduces the full guide content and code examples for React and HTML usage patterns. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| this.addEventListener('click', this.#handleActivate); | ||
| this.addEventListener('keydown', this.#handleKeydown); | ||
| } | ||
|
|
| const visible = time.currentTime < 30 && !playback.paused; | ||
| this.toggleAttribute('data-visible', visible); | ||
| this.style.opacity = visible ? '1' : '0'; | ||
| this.style.pointerEvents = visible ? 'auto' : 'none'; | ||
| } |
| }; | ||
|
|
||
| #handleKeydown = (event: KeyboardEvent) => { | ||
| if (event.key === 'Enter' || event.key === ' ') { |
Merge "Read player state" and "Dispatch actions" into a single section that introduces features, state, and actions together. Fix HTML examples that incorrectly mixed selectors (calling volume actions through a playback selector). Correct Provider vs Container distinction — video-player is the provider, not the container. Remove "Style with player state" section that made inaccurate claims about automatic data attributes and nonexistent design tokens. Add Actions column to features table. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
|
||
| <FrameworkCase frameworks={["react"]}> | ||
|
|
||
| For button-like controls, the <DocsLink slug="reference/use-button">`useButton`</DocsLink> hook handles keyboard activation (Enter and Space) and ARIA attributes. |
There was a problem hiding this comment.
The useButton hook is mentioned for button-like controls but not used below.
| style={{ | ||
| position: 'absolute', | ||
| bottom: '5rem', | ||
| right: '1rem', | ||
| opacity: visible ? 1 : 0, | ||
| pointerEvents: visible ? 'auto' : 'none', | ||
| transition: 'opacity 200ms', | ||
| }} |
There was a problem hiding this comment.
To keep in the spirit of the library maybe we should use data attrs and CSS? E.g., data-visible
| this.addEventListener('click', this.#handleActivate); | ||
| this.addEventListener('keydown', this.#handleKeydown); |
| import { ReactiveElement } from '@videojs/element'; | ||
| import { PlayerController, playerContext, selectTime, selectPlayback } from '@videojs/html'; |
There was a problem hiding this comment.
I think we should re-export ReactiveElement from html package (if we aren't yet). We also have MediaElement which extends ReactiveElement and has destroy lifecycle baked in.
| const time = this.#time.value; | ||
| const playback = this.#playback.value; | ||
| if (!time || !playback) return; |
There was a problem hiding this comment.
nit: new line above
suggestion: Comment briefly explaining why these can be undefined (store features are configured so some features might be missing)
| this.toggleAttribute('data-visible', visible); | ||
| this.style.opacity = visible ? '1' : '0'; | ||
| this.style.pointerEvents = visible ? 'auto' : 'none'; |
There was a problem hiding this comment.
There's a data-visible attribute, we should move the opacity and pointer-events to CSS.
🤖 Style reviewHTML path in "Place your component" — skeleton may not earn its place The React path is lean: use the hook, done. The HTML path introduces Consider replacing the skeleton with prose that explains the pattern, then letting the full example be the first time the reader sees a complete class:
This gives the HTML reader the mental model (ReactiveElement + PlayerController + selector → automatic Written by Claude Code |
There was a problem hiding this comment.
🤖 Technical Review
The APIs referenced are all correct — Player.usePlayer, PlayerController, playerContext, selectPlayback, selectTime, and all state/action names match the source code. Here are issues not already covered by other comments:
1. await store.play() in component render scope (line 55)
The React snippet mixes hook calls with await:
const store = Player.usePlayer();
await store.play();The usePlayer() calls establish this as a component render function, where await is not valid. This should either be shown inside an event handler/effect, or drop the await and just note that play() returns a Promise.
2. static tagName is unused (line 199)
The full HTML example declares static tagName = 'skip-intro-button' but then registers with customElements.define('skip-intro-button', SkipIntroButtonElement). static tagName is only consumed by safeDefine() — it does nothing with direct customElements.define(). Either switch to safeDefine(SkipIntroButtonElement) or remove static tagName.
3. update() omits the changed parameter (lines 134, 213)
Both the snippet and full example override update() with no parameter:
update() {
super.update();The actual ReactiveElement signature is update(changed: PropertyValues) and the library's own JSDoc example passes it through: super.update(changed). The guide should match the library's convention so users learn the right pattern, especially since changed is useful for conditional update logic.
4. HTML element never sets visible text (full example)
The React example renders <button>Skip intro</button> with visible text. The HTML custom element class never sets textContent or creates a child <button>. Combined with the empty <skip-intro-button></skip-intro-button> in the placement section (line 121), the button renders visually empty — only aria-label provides text for screen readers. Should either set this.textContent = 'Skip intro' in connectedCallback(), show inner HTML in the markup, or create a shadow DOM with a <button>.
5. Unresolved TODO (line 149)
TODO: Link to concepts/accessibility once that page is merged
The concepts/accessibility page exists and is already in the sidebar, so this can be resolved now with a <DocsLink> link.
6. React full example: missing createPlayer context
The React example uses Player.usePlayer((s) => s.currentTime) and assumes it's a number. This works because createPlayer is called with features that include time — but the guide never shows the createPlayer setup. A brief note or link to createPlayer would help users understand why these properties are available and typed.
Written by Claude Code
- Use standalone `usePlayer` import from @videojs/react instead of `Player.usePlayer` namespace - Switch from ReactiveElement to MediaElement from @videojs/html - Use data-visible attr + CSS instead of inline styles (React and HTML) - Add AbortController cleanup pattern for event listeners - Fix ARIA button keyboard pattern (Space activates on keyup) - Toggle tabindex when hidden to remove from tab order - Add visible text to HTML element markup - Resolve TODO: link to accessibility concept page - Present full examples in tabbed code blocks (TS + CSS) - Use Shiki focus annotations instead of inline comments - Add explanatory comments for non-obvious patterns - Remove unused useButton mention from accessibility section - Add annotated skeleton in "Place your component" HTML section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Drop unused `static tagName` from the full skip-intro example (the guide registers via `customElements.define()` directly, so the field is dead code from a userland perspective). - Forward `changed: PropertyValues` to `super.update()` in both the intro skeleton and the full example, matching first-party convention and the actual `ReactiveElement` signature. `PropertyValues` now imports from `@videojs/html` (re-exported via #1472). - Trim the "Place your component" skeleton — drop comments and `customElements.define` line — so it's a minimal anchor for what's required, leaving the full example as the first complete class. Addresses review feedback on #1008. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Drop redundant "just" before "like built-in controls" (words-to-avoid). - Replace emdash bullet pattern with colons in "You might not need a custom component" — five identical emdashes triggered the "go easy on emdashes; prefer commas, colons, or semicolons" rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- HTML "Place your component" now mentions `<media-container>` for
fullscreen + user activity parity with React. The example moves
`<skip-intro-button>` inside `<video-skin>` so it lives in
`<media-container>` via the skin's default slot.
- Add `[!code focus]` markers on the wrapping elements being discussed
in both React and HTML placement code blocks.
- Reframe the "Use player state and actions" intro to lead with
intent ("Need access to player state or actions?") instead of
declaration.
- Drop the prescriptive accessibility prose; the section is a heading
+ link card pointing to the dedicated guide.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@cursor review |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit c5dac41. Configure here.
Note
Depends on #1007
Add a new "Build your own component" how-to guide covering how to read player state, dispatch actions, place components in the player, style with player state, and make components accessible. Includes a full "skip intro" button example for both React and HTML frameworks.
Note
Low Risk
Low risk documentation-only change that adds a new guide and links/navigation entries; no runtime/player code is modified.
Overview
Adds a new how-to guide,
how-to/build-your-own-component, explaining how to build custom player UI components for both React and HTML (state/actions access, placement in the player, and accessibility), including a full “skip intro” example.Updates the docs navigation to surface the new guide: it’s added to the How to sidebar and linked from the
concepts/overviewpage.Reviewed by Cursor Bugbot for commit c5dac41. Bugbot is set up for automated code reviews on this repo. Configure here.