I will not be investing significant effort in the very near future to review and address issues on this repository. However I do want my software to be useable!
If you have an issue that must be resolved for your work, please open a pull request to fix it, and send me a direct email to make sure that I see it. I ignore most messages from GitHub these days.
I'm also happy to help out if you have a question about how to use the library.
My email can be found at the top of this commit.
Keep in mind that I have a full-time job and a personal life as well as other hobbies that have taken priority over open source, so I might not respond immediately. But don't hesitate to follow up after a few days if you think I've missed your email.
Similar to Facebook's GIF toggle UI, this React component displays a still image preview by default, and swaps in an animated GIF when clicked. The images are preloaded as soon as the component mounts, or whenever a new source is passed.
Note: Unlike Facebook's UI, which uses an HTML video element to preserve playback progress, this component uses the actual GIF and will be reset on each click.
npm install react-gif-player react react-dom
If you're unable to use npm and need production-ready scripts, check out the releases.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1">
<!-- gifplayer.css v0.4.2 -->
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/gifplayer.css">
</head>
<body>
<div id="cat"></div>
<!-- react/react-dom served over CDN -->
<script src="https://unpkg.com/[email protected]/umd/react.development.js"></script>
<script src="https://unpkg.com/[email protected]/umd/react-dom.development.js"></script>
<!-- gifplayer.js v0.4.2 -->
<script src="https://unpkg.com/[email protected]/dist/gifplayer.js"></script>
<script>
ReactDOM.render(
React.createElement(GifPlayer, {
gif: '/img/cat.gif',
still: '/img/cat.jpg'
}),
document.getElementById('cat')
);
</script>
</body>
</html>var React = require('react');
var ReactDOM = require('react-dom');
var GifPlayer = require('react-gif-player');
// with JSX
ReactDOM.render(
<GifPlayer gif="/img/cat.gif" still="/img/cat.jpg" />,
document.getElementById('cat')
);Options can be passed to the GifPlayer element as props.
-
gif: a string address to an animated GIF image. -
still: a string address to a still preview of the GIF (e.g. JPG, PNG, etc.) -
autoplay: a boolean which can be settrueif you want to immediately bombard your user with a moving GIF as soon as it's available -
onTogglePlay: a function which is called whenever the GIF toggles between playing and paused. Receives one argument,playing, which is a boolean. -
pauseRef: a function callback is called with another function,pause- this can be saved and called later to remotely pause the playing of the GIF, in such cases where that might be desired. For example, you might want to stop the GIF when it scrolls offscreen. The word "ref" is used because its usage pattern is similar to React element refs:// here's an example class MyGifWrapper extends React.Component { componentDidMount () { addEventListenerWhenGifFlowsOffscreen(this.pauseGif); } render () { return ( <GifPlayer gif={src} still={still} pauseRef={pause => this.pauseGif = pause} /> ); } }
Still confused? Here's a jsfiddle which shows how to use
pauseRef. -
Any other attribute available on the HTML
imgtag can be passed as well (excludingsrc, which would be overwritten), though keep in mind React's version of that attribute may be different than you expect.
GifPlayer expects one or both of the gif and still props. If one is left out, the other will be used as a fallback.
However, if only a gif prop is provided, the first frame will be extracted and used as the still preview as soon as the GIF image has fully loaded.
The disadvantage of not providing a still prop, even though a stand-in will be generated, is that your GIF must fully load before the still frame appears instead of the (likely slowly moving) GIF.
One streamlined way to generate a still frame ahead of time is to incorporate the gif-frames module, which has only pure JavaScript dependencies, into your build process.
e.g.
var gifFrames = require('gif-frames');
var fs = require('fs');
gifFrames({ url: 'src/image.gif', frames: 0 }).then(function (frameData) {
frameData[0].getImageStream().pipe(fs.createWriteStream('build/still.jpg'));
});If you need finer-tuned control over image quality, you can try Gifsicle.
Important: In order for the default styles to be used, dist/gifplayer.css must be included in your HTML.
CSS styles can be overridden easily. To add a border around the image, try including this CSS after including the default styles:
.gif_player img {
border: 3px solid cornflowerblue;
}If you preprocess your styles with Sass, you can have more powerful control via Sass variables. The defaults are located at the top of src/GifPlayer.scss:
$gif_btn_bg_base_color: #000 !default;
$gif_btn_bg_opacity: 0.5 !default;
$gif_btn_bg_opacity_hover: 0.7 !default;
// ...etcThe !default flag means that declaring alternatives before including the default styles will override them.
// Include var overrides before default styles import
$gif_btn_bg_base_color: gold;
$gif_btn_text_color: cornflowerblue;
$gif_btn_font_family: serif;
// Using webpack css/sass module import syntax
@import '~react-gif-player/src/GifPlayer';
// include other overrides afterward
.gif_player {
margin: 1rem;
img {
border: 2px solid #222;
}
}For building and testing instructions, see CONTRIBUTING.md.