livephoto.js

A lightweight, dependency-free JavaScript library for perfectly replicating the Live Photo (dynamic photo) effect taken with mobile phones on web pages.

Usage Showcase

Dynamic Image Showcase
Live
Dynamic Image Showcase

Installation

Download the latest versions of livephoto.js and livephoto.css files from GitHub and place them in your web project.

1
git clone https://github.com/cykzht/livephoto.js.git

Full Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
<!DOCTYPE html>
<html lang="zh-cn">
  <head>
    <meta charset="UTF-8" />
    <title>LivePhoto Demo</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- Import styles -->
    <link rel="stylesheet" href="livephoto.css" />
    <!-- Override styles -->
    <style>
      .live-photo-container {
        border-radius: 0 !important;
      }
      .live-photo-video {
        border-radius: 0 !important;
      }
    </style>
  </head>
  <body>
    <!-- Live Photo container example -->
     <!-- Can set width and height -->
    <div class="live-photo-container" style="width: 400px; height: 300px">
      <img src="path/IMG.jpg" alt="Description text" class="live-photo-static" />
      <video muted playsinline class="live-photo-video">
        <source src="path/VID.mp4" type="video/mp4" />
      </video>
    </div>
    <!-- Two images in one row -->
    <div class="image-grid">
      <div class="image-column">
        <div class="live-photo-container">
          <img src="path/IMG.jpg" alt="Description text" class="live-photo-static" />
          <video muted playsinline class="live-photo-video">
            <source src="path/VID.mp4" type="video/mp4" />
          </video>
        </div>
      </div>
      <div class="image-column">
        <div class="live-photo-container">
          <img src="path/IMG.jpg" alt="Description text" class="live-photo-static" />
          <video muted playsinline class="live-photo-video">
            <source src="path/VID.mp4" type="video/mp4" />
          </video>
        </div>
      </div>
    </div>

    <!-- Import script -->
    <script src="livephoto.js"></script>
    <script>
      // Configuration object
      const config = {
        autoplay: true,
        hover_to_play: true,
        click_to_play: true,
        lazy_load: true,
        threshold: 0.8,
        badge: true,
        badge_text: "Live",
        badge_position: "bottom-left",
        loading_animation: true,
        preload: "auto",
        keep_observing: false,
        hover_delay: 300,
        weixin_disable_autoplay: true,
      };
      // Call the initialization function
      initLivePhoto(config);
    </script>
  </body>
</html>

Import Components

You need to import the livephoto.css and livephoto.js files in your HTML file:

1
2
<link rel="stylesheet" href="livephoto.css" />
<script src="livephoto.js"></script>

HTML Structure

In your HTML, create a container that includes both a static image and a video. Ensure the image and video file paths are correct.

1
2
3
4
5
6
<div class="live-photo-container">
    <img src="path/IMG.jpg" alt="Description text" class="live-photo-static" />
    <video muted playsinline class="live-photo-video">
        <source src="path/VID.mp4" type="video/mp4" />
    </video>
</div>

One Row with Two Images Layout Example

A simple grid layout class is built into the CSS, which can easily implement a layout with two images in one row.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<div class="image-grid">
  <div class="image-column">
    <div class="live-photo-container">
      <img src="path/IMG.jpg" alt="Description text" class="live-photo-static" />
      <video muted playsinline class="live-photo-video">
        <source src="path/VID.mp4" type="video/mp4" />
      </video>
    </div>
  </div>
  <div class="image-column">
    <div class="live-photo-container">
      <img src="path/IMG.jpg" alt="Description text" class="live-photo-static" />
      <video muted playsinline class="live-photo-video">
        <source src="path/VID.mp4" type="video/mp4" />
      </video>
    </div>
  </div>
</div>

Override Styles

If you don’t like the default styles, you can override them with CSS (for example, removing rounded corners):

1
2
3
4
5
6
7
8
<style>
  .live-photo-container {
    border-radius: 0 !important;
  }
  .live-photo-video {
    border-radius: 0 !important;
  }
</style>

Initialization

After importing livephoto.js, call the initLivePhoto function to initialize the component. You can pass a configuration object to customize the component’s behavior.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const config = {
    autoplay: true, // Whether to auto-play (when entering the viewport)
    hover_to_play: true,  // Whether to enable hover-play
    click_to_play: true,  // Whether to enable click-play
    lazy_load: true,  // Whether to enable lazy loading
    threshold: 0.8, // The visible ratio that triggers auto-play
    badge: true,  // Whether to display the Live badge
    badge_text: "Live", // Badge text
    badge_position: "bottom-left",  // Badge position: bottom-left, bottom-right, top-left, top-right
    loading_animation: true,  // Whether to display a loading animation
    preload: "auto",  // Preload option: 'auto', 'metadata', 'none'
    keep_observing: false,  // Whether to continue observing the element
    hover_delay: 300, // Hover delay time (milliseconds)
    weixin_disable_autoplay: true,  // Whether to disable auto-play in WeChat's built-in browser
};
initLivePhoto(config);

Notes

  1. Video Format: It is recommended to use MP4 format encoded with H.264 to ensure compatibility with most browsers.
  2. Performance: Although the plugin has been optimized, please note that video files should not be too large, and it is recommended to host video resources on a fast CDN.
  3. Browser Support: Ensure your browser supports HTML5 video playback. After testing, Xiaomi Browser will convert the video to a video player, although it does not affect viewing, you will lose the opportunity to download the static image and the dynamic playback experience.
  4. WeChat Browser: Due to the strict restrictions on auto-play in WeChat’s built-in browser, it is recommended to enable the weixin_disable_autoplay option to avoid white screen issues caused by auto-play.

Contributions

Welcome to submit Issues and Pull Requests!

License

MIT

Support

If this plugin has helped you, please give a star ⭐. If you encounter any problems while using it, please submit an Issue.