Media Hooks
Hooks for managing media state, buffering, playback controls, and video properties.
useBuffering()
A hook to check and control the video's buffering state.
Usage
import { useBuffering } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { buffering } = useBuffering();
// ...
};Return Type
interface UseBufferingReturn {
buffering: boolean;
setBuffering: (isBuffering: boolean) => void;
}Returns
| Value | Type | Description |
|---|---|---|
buffering | boolean | A boolean indicating whether the video is currently buffering (true) or not (false). |
setBuffering | (isBuffering: boolean) => void | A function that allows you to manually set the buffering state. This is primarily used internally but can be useful for custom buffering indicators. |
<VideoPlayer.LoadingSpinner /> uses this hook to display a loading spinner when the video is buffering.
Example
import { useBuffering } from 'react-native-video-toolkit';
import { ActivityIndicator } from 'react-native';
const MyBufferingIndicator = () => {
const { buffering } = useBuffering();
if (buffering) {
return <ActivityIndicator size="large" color="#fff" />;
}
return null;
};
export default MyBufferingIndicator;useControlsVisibility()
A hook for managing the visibility of the video player controls, including functions to show, hide, or toggle them.
The functions are stable and shared by every caller: a VideoProvider runs one auto-hide timer, and showing controls that are already visible doesn't re-render anything.
Usage
import { useControlsVisibility } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { showControls, hideControls } = useControlsVisibility();
// ...
};Return Type
interface UseControlsVisibilityReturn {
showControls: () => void;
hideControls: () => void;
toggleControls: () => void;
controlsVisible: boolean;
}Returns
| Value | Type | Description |
|---|---|---|
showControls | () => void | A function that makes the video controls visible. |
hideControls | () => void | A function that hides the video controls. |
toggleControls | () => void | A function that toggles the visibility of the controls (shows if hidden, hides if visible). |
controlsVisible | boolean | Whether the controls are currently visible. Use this for custom animations and conditional rendering. |
Example
import { useControlsVisibility } from 'react-native-video-toolkit';
import { View, Button } from 'react-native';
import React from 'react';
const MyCustomControl = () => {
const { showControls, hideControls, toggleControls } = useControlsVisibility();
return (
<View>
<Button title="Show" onPress={showControls} />
<Button title="Hide" onPress={hideControls} />
<Button title="Toggle" onPress={toggleControls} />
</View>
);
};
export default MyCustomControl;useFullscreen()
A hook for managing the video player's fullscreen mode.
With enableScreenRotation (the default), entering fullscreen locks the screen to landscape. Exiting returns phones to portrait and lets tablets and foldables rotate freely again. On web it fullscreens the player that called it, so a page can have several.
Usage
import { useFullscreen } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { fullscreen, toggleFullscreen, enterFullscreen, exitFullscreen } = useFullscreen();
// ...
};Return Type
interface UseFullscreenReturn {
fullscreen: boolean;
toggleFullscreen: () => Promise<void>;
enterFullscreen: () => Promise<void>;
exitFullscreen: () => Promise<void>;
}Returns
| Value | Type | Description |
|---|---|---|
fullscreen | boolean | A boolean indicating whether the video player is currently in fullscreen mode. |
toggleFullscreen | () => Promise<void> | A function that toggles the fullscreen mode. This function also handles screen orientation locking if enableScreenRotation is true in VideoPlayerConfig. |
enterFullscreen | () => Promise<void> | A function that enters fullscreen mode. No-op if already in fullscreen. Handles screen orientation locking automatically. |
exitFullscreen | () => Promise<void> | A function that exits fullscreen mode. No-op if not in fullscreen. Handles screen orientation unlocking automatically. |
<VideoPlayer.FullscreenButton /> uses this hook to provide a button for toggling fullscreen mode.
Handles tap gestures for toggling fullscreen mode.
This hooks calls the useOrientation hook internally to manage screen orientation when entering/exiting fullscreen mode. If you are also using the useOrientation hook in your component, ensure that both hooks are configured consistently to avoid conflicts.
Example
import { useFullscreen } from 'react-native-video-toolkit';
import React from 'react';
const MyFullscreenButton = () => {
const { fullscreen, toggleFullscreen } = useFullscreen();
return <BaseIconButton IconComponent={FullscreenIcon} onTap={toggleFullscreen} />;
};
export default MyFullscreenButton;usePictureInPicture()
A hook for moving the video into a floating picture-in-picture window and back.
Usage
import { usePictureInPicture } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { pictureInPicture, togglePictureInPicture, enterPictureInPicture, exitPictureInPicture } =
usePictureInPicture();
// ...
};Return Type
interface UsePictureInPictureReturn {
pictureInPicture: boolean;
supported: boolean;
enterPictureInPicture: () => void;
exitPictureInPicture: () => void;
togglePictureInPicture: () => void;
}Returns
| Value | Type | Description |
|---|---|---|
pictureInPicture | boolean | Whether the video is playing in picture-in-picture. Also updates when the user closes the window. |
enterPictureInPicture | () => void | Moves the video into a floating picture-in-picture window. |
exitPictureInPicture | () => void | Brings the video back from picture-in-picture. |
togglePictureInPicture | () => void | Enters or exits picture-in-picture. |
supported | boolean | Whether picture-in-picture can work on this device and in this app; see isPictureInPictureSupported. |
<VideoPlayer.PictureInPictureButton /> uses this hook.
Picture-in-picture needs native setup (the audio background mode on iOS, supportsPictureInPicture on Android); see
the button's setup section.
usePlayback()
A hook for controlling the video's playback state (play, pause).
Usage
import { usePlayback } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { isPlaying, togglePlayPause } = usePlayback();
// ...
};Return Type
interface UsePlaybackReturn {
isPlaying: boolean;
ended: boolean;
togglePlayPause: () => void;
setPlaying: (isPlaying: boolean) => void;
}Returns
| Value | Type | Description |
|---|---|---|
isPlaying | boolean | A boolean indicating whether the video is currently playing. |
ended | boolean | Whether playback reached the end. Cleared when it plays again or a new source loads. |
togglePlayPause | () => void | A function that toggles the video between playing and paused states. |
setPlaying | (isPlaying: boolean) => void | A function that directly sets the playing state of the video. |
<VideoPlayer.PlayPauseButton /> uses this hook to provide a button for toggling playback. Handles tap
gestures for toggling play/pause state.
Example
import { usePlayback } from 'react-native-video-toolkit';
import React from 'react';
const MyPlayPauseButton = () => {
const { isPlaying, togglePlayPause } = usePlayback();
return <BaseIconButton IconComponent={PlayPauseIcon} onTap={togglePlayPause} />;
};
export default MyPlayPauseButton;usePlaybackRate()
A hook for controlling video playback rate.
Usage
import { usePlaybackRate } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { playbackRate, setPlaybackRate } = usePlaybackRate();
// ...
};Return Type
interface UsePlaybackRateReturn {
playbackRate: number;
setPlaybackRate: (playbackRate: number) => void;
}Returns
| Value | Type | Description |
|---|---|---|
playbackRate | number | A number indicating the current playback rate of the video. |
setPlaybackRate | (playbackRate: number) => void | A function to set the playback rate of the video. |
Example
import { usePlaybackRate } from 'react-native-video-toolkit';
import { Button } from 'react-native';
const MyPlaybackRateButton = () => {
const { playbackRate, setPlaybackRate } = usePlaybackRate();
return <Button title={`Set playback rate to 2x`} onPress={() => setPlaybackRate(2)} />;
};
export default MyPlaybackRateButton;useProgress()
A hook for accessing and controlling the video's current playback time and duration.
It's the way to read the playback position, which isn't in useVideo().state. The position changes on every progress event (twice a second while playing), so only the components that call useProgress() re-render with it.
Usage
import { useProgress } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { currentTime, duration, seek } = useProgress();
// ...
};Return Type
interface UseProgressReturn {
currentTime: number;
duration: number;
playableDuration: number;
seek: (time: number) => void;
setCurrentTime: (time: number) => void;
setDuration: (duration: number) => void;
setPlayableDuration: (playableDuration: number) => void;
}Returns
| Value | Type | Description |
|---|---|---|
currentTime | number | The current playback time of the video in seconds. |
playableDuration | number | The playable duration of the video in seconds. |
duration | number | The total duration of the video in seconds. |
seek | (time: number) => void | A function that seeks the video to a specific time in seconds. |
setCurrentTime | (time: number) => void | A function that manually sets the current time state. Primarily used internally. |
setPlayableDuration | (playableDuration: number) => void | A function that manually sets the playable duration state. Primarily used internally. |
setDuration | (duration: number) => void | A function that manually sets the duration state. Primarily used internally. |
<VideoPlayer.ProgressBar />uses this hook to display and control video progress.<VideoPlayer.TimeDisplay />uses this hook to show the current time and duration.
Example
import { useProgress } from 'react-native-video-toolkit';
import Slider from '@react-native-community/slider';
import { View, Text } from 'react-native';
import React from 'react';
const MyProgressBar = () => {
const { currentTime, duration, seek } = useProgress();
const formatTime = (seconds: number) => {
const minutes = Math.floor(seconds / 60);
const remainingSeconds = Math.floor(seconds % 60);
return `${minutes}:${remainingSeconds < 10 ? '0' : ''}${remainingSeconds}`;
};
return (
<View>
<Text>
{formatTime(currentTime)} / {formatTime(duration)}
</Text>
<Slider minimumValue={0} maximumValue={1} value={currentTime} onSlidingComplete={seek} />
</View>
);
};
export default MyProgressBar;useVolume()
A hook for managing the video's volume and mute state.
Usage
import { useVolume } from 'react-native-video-toolkit';
export const MyComponent = () => {
const { volume, muted, toggleMute } = useVolume();
// ...
};Return Type
interface UseVolumeReturn {
volume: number;
muted: boolean;
setVolume: (volume: number) => void;
toggleMute: () => void;
}Returns
| Value | Type | Description |
|---|---|---|
volume | number | The current volume level of the video, a number between 0 and 1. |
muted | boolean | A boolean indicating whether the video is currently muted. |
setVolume | (volume: number) => void | A function that sets the video's volume to a specific level (0 to 1). |
toggleMute | () => void | A function that toggles the mute state of the video. |
<VideoPlayer.MuteButton /> uses this hook to provide a button for toggling mute.
Example
import { useVolume } from 'react-native-video-toolkit';
import Slider from '@react-native-community/slider'; // Example slider component
import { View } from 'react-native'; // Assuming View is from react-native
import React from 'react';
const MyVolumeControl = () => {
const { volume, muted, setVolume, toggleMute } = useVolume();
return (
<View>
<BaseIconButton IconComponent={MuteIcon} onTap={toggleMute} />;
<Slider minimumValue={0} maximumValue={1} value={volume} onSlidingComplete={setVolume} disabled={muted} />
</View>
);
};
export default MyVolumeControl;useOrientation()
A comprehensive hook for handling device orientation and rotation logic.
Usage
import { useOrientation } from 'react-native-video-toolkit';
export const MyComponent = () => {
const orientation = useOrientation();
return (
<View>
<Text>Device Type: {orientation.deviceType}</Text>
<Text>Should Auto Rotate: {orientation.shouldAutoRotate ? 'Yes' : 'No'}</Text>
</View>
);
};Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
customConfig | RotationConfig | undefined | Optional custom rotation configuration to override default behavior. |
Returns
| Value | Type | Description |
|---|---|---|
deviceType | DeviceType | The detected type of the device (e.g., 'phone', 'tablet', 'tv', 'foldable'). |
platformCapabilities | OrientationCapabilities | An object detailing the platform's capabilities regarding orientation control and fullscreen support. |
shouldAutoRotate | boolean | Indicates if the device should automatically rotate based on content and configuration. |
isLandscapeOptimal | boolean | True if landscape orientation is considered optimal for the current content/device. |
rotationConfig | RotationConfig | The active rotation configuration, including any custom overrides. |
controlsConfig | object | Configuration related to video controls based on orientation. |
orientationLocked | boolean | True if the device's orientation is currently locked. |
lockToLandscape | () => Promise<boolean> | Asynchronously locks the device orientation to landscape. Returns true on success. |
lockToPortrait | () => Promise<boolean> | Asynchronously locks the device orientation to portrait. Returns true on success. |
unlockOrientation | () => Promise<boolean> | Asynchronously unlocks the device orientation. Returns true on success. |
getFullscreenStrategy | () => OrientationStrategy | Returns an object describing the optimal orientation strategy for fullscreen mode. |
handleEnterFullscreen | () => Promise<void> | Handles orientation changes specifically for entering fullscreen mode. |
handleExitFullscreen | () => Promise<void> | Handles orientation changes specifically for exiting fullscreen mode. |
Example
import React, { useState } from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import { useOrientation } from 'react-native-video-toolkit';
const OrientationDemo = () => {
const orientation = useOrientation();
const [message, setMessage] = useState('');
const handleToggleLock = async () => {
if (orientation.orientationLocked) {
const success = await orientation.unlockOrientation();
setMessage(success ? 'Orientation unlocked.' : 'Failed to unlock orientation.');
} else {
const success = await orientation.lockToLandscape();
setMessage(success ? 'Orientation locked to landscape.' : 'Failed to lock to landscape.');
}
};
return (
<View style={styles.container}>
<Text style={styles.header}>Orientation Hook Demo</Text>
<Text>Device Type: {orientation.deviceType}</Text>
<Text>Orientation Locked: {orientation.orientationLocked ? 'Yes' : 'No'}</Text>
<Text>Should Auto Rotate: {orientation.shouldAutoRotate ? 'Yes' : 'No'}</Text>
<Text>Message: {message}</Text>
<View style={styles.buttonContainer}>
<Button
title={orientation.orientationLocked ? 'Unlock Orientation' : 'Lock to Landscape'}
onPress={handleToggleLock}
/>
</View>
</View>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
padding: 20,
},
header: {
fontSize: 20,
fontWeight: 'bold',
marginBottom: 10,
},
buttonContainer: {
flexDirection: 'row',
marginTop: 20,
gap: 10,
},
});
export default OrientationDemo;