UI

Gesture

This component is used to perform media actions based on user gestures (e.g., double click for fullscreen).

# Import

        import '@vidstack/player/define/vds-gesture.js';

      

        <script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@vidstack/player@next/cdn/define/vds-gesture.js"
></script>

      

# Usage

The <vds-gesture> component enables actions to be performed on the media provider based on defined user gestures. Some examples include:

• Clicking the player to toggle playback.
• Double-clicking the player to toggle fullscreen.
• Tapping the sides of the player to seek forwards or backwards.
• Pausing media when the user's mouse leaves the player.

          
1
2
3
4
		    

# Type

The type property seen in the snippet above can be any valid DOM event type (e.g., touchstart, mouseleave, etc.). An event listener is attached to the given event type on the media container, and when fired, it will trigger the action on the media provider.

# Action

The action property represents the media state change that will occur when the gesture is performed.

        export type GestureAction =
  | 'play'
  | 'pause'
  | 'mute'
  | 'unmute'
  | 'enter-fullscreen'
  | 'exit-fullscreen'
  | `seek:${number}`
  | `toggle:${'paused' | 'muted' | 'fullscreen'}`;

      

# Repeat

The repeat property represents of number of times a gesture event type should be repeated before the action is performed. If you want an event to occur twice before the action is performed, this will be a single repetition (i.e., value of 1).

# Priority

The priority property represents the level of importance given to this gesture. If multiple gestures occur at the same time, the priority will determine which gesture actions are performed. Higher priority gestures in a single batch will cause lower level priorities to be ignored.

Priorities are useful for layering gestures. You can think of priority like z-index, except lower priority values mean a higher index:

# Contextual Menu

Due to event listeners being attached directly to the media container, they don't block the video element's contextual menu (i.e., the menu opened when you right-click the video element):

# Styling

          
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
		    

In the preview above, we've applied the following gestures:

• Pause media when the user's mouse leaves the player.
• Toggle playback when the user clicks the player.
• Toggle fullscreen when the user double clicks the player.
• Seek playback backwards thirty seconds when the user double-clicks on the left region (25%) of the player.
• Seek playback forwards thirty seconds when the user double-clicks on the right region (25%) of the player.

The click gesture priorities from highest to lowest is: seeking -> toggling fullscreen -> toggling playback.

Notice pausing on mouseleave will occur regardless of the priority set because it doesn't conflict with other gesture event types (i.e., they generally don't occur at the same time).