https://github.com/interactive-video-labs/interactive-video-react-wrapper
⚛️ Thin React wrapper for the @interactive-video-labs/core library. Seamlessly embed cue-based interactive video players in your React apps using simple props and event handlers. Lightweight, declarative, and fully type-safe.
https://github.com/interactive-video-labs/interactive-video-react-wrapper
cue-points declarative-ui education-tech event-driven interactive-video npm-package react react-component react-wrapper typescript video-interaction video-player
Last synced: 6 months ago
JSON representation
⚛️ Thin React wrapper for the @interactive-video-labs/core library. Seamlessly embed cue-based interactive video players in your React apps using simple props and event handlers. Lightweight, declarative, and fully type-safe.
- Host: GitHub
- URL: https://github.com/interactive-video-labs/interactive-video-react-wrapper
- Owner: interactive-video-labs
- License: mit
- Created: 2025-07-31T16:07:18.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-07-31T20:43:42.000Z (6 months ago)
- Last Synced: 2025-07-31T22:34:40.457Z (6 months ago)
- Topics: cue-points, declarative-ui, education-tech, event-driven, interactive-video, npm-package, react, react-component, react-wrapper, typescript, video-interaction, video-player
- Language: TypeScript
- Homepage:
- Size: 32.2 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# @interactive-video-labs/react
Welcome to `@interactive-video-labs/react` — a lightweight React wrapper around the `@interactive-video-labs/core` engine for cue-driven interactive video experiences.
This wrapper makes it easy to embed interactive video players in React apps using familiar props and event handlers, while keeping close to the core API.
---
## Introduction
`@interactive-video-labs/react` is a thin React component that provides a convenient way to integrate interactive video experiences into your React applications. It leverages the powerful `@interactive-video-labs/core` engine, allowing you to easily manage video playback, cue points, and analytics within a familiar React paradigm.
## Features
* **Easy Integration**: Seamlessly embed interactive videos into your React components.
* **Cue Point Management**: Load and manage cue points for dynamic video interactions.
* **Analytics Events**: Receive detailed analytics events from the video player to track user engagement.
* **Localization**: Support for player localization through translations.
* **Direct Core API Access**: Provides a React-friendly interface while maintaining close alignment with the core IVLabsPlayer API.
## Installation
You can install the package using npm or pnpm:
```bash
pnpm add @interactive-video-labs/react @interactive-video-labs/core react react-dom
# or
npm install @interactive-video-labs/react @interactive-video-labs/core react react-dom
```
## Usage
To use the `InteractiveVideo` component, simply import it and pass the necessary props. The `videoUrl` prop is mandatory.
```tsx
import React from 'react';
import { InteractiveVideo } from '@interactive-video-labs/react';
const MyVideoPlayer = () => {
return (
{
console.log('Analytics Event:', event, payload);
// Handle analytics events, e.g., send to a tracking service
}}
cues={[
{ time: 10, id: 'intro-cue', type: 'pause' },
{ time: 25, id: 'question-cue', type: 'custom', data: { question: 'What is your favorite color?' } },
]}
translations={{
en: {
play: 'Play Video',
pause: 'Pause Video',
},
}}
/>
);
};
export default MyVideoPlayer;
```
## Props
The `InteractiveVideo` component accepts the following props:
* `videoUrl` (string, **required**): The URL of the video to be played.
* `onAnalyticsEvent` (function, optional): A callback function that is triggered when an analytics event occurs. It receives the `event` name and an optional `payload`.
* `event`: `PLAYER_LOADED`, `VIDEO_STARTED`, `VIDEO_PAUSED`, `VIDEO_ENDED`, `CUE_TRIGGERED`, `INTERACTION_COMPLETED`, `ERROR`.
* `payload`: An object containing event-specific data.
* `cues` (CuePoint[], optional): An array of cue points to load into the player. Each `CuePoint` object should conform to the `@interactive-video-labs/core` `CuePoint` interface.
* `translations` (Translations, optional): An object containing translations for player localization. This should conform to the `@interactive-video-labs/core` `Translations` interface.
* `...restOptions` (PlayerConfig, optional): Any other valid `PlayerConfig` options from `@interactive-video-labs/core` (excluding `videoUrl`, `cues`, and `translations`). This allows for direct pass-through of core player configurations like `autoplay`, `loop`, `controls`, `locale`, etc.
## Development
To set up the development environment:
1. Clone the repository.
2. Install dependencies:
```bash
pnpm install
```
3. Build the project:
```bash
pnpm build
```
4. Run tests:
```bash
pnpm test
```
5. Run examples:
```bash
pnpm serve-examples
```
## Contributing
We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.