@giphy/js-components

A lightweight set of components, focused on ease-of-use and performance.

Try it out:

A note about pingbacks

This SDK sends analytics events back to GIPHY in the form of pingbacks to help us improve the quality of search results for your users.

Grid

Use renderGrid(props, target) to render a grid to a target element

Bare Bones Example

// use @giphy/js-fetch-api to fetch gifs
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')
// fetch 10 gifs at a time as the user scrolls (offset is handled by the grid)
const fetchGifs = (offset: number) => gf.trending({ offset, limit: 10 })
// render a grid
renderGrid({ width: 800, fetchGifs }, targetEl)

renderGrid options

prop	type	default	description
width	number	undefined	The width of the grid
fetchGifs	(offset:number) => Promise<GifsResult>	undefined	A function that returns a Promise. Use @giphy/js-fetch-api
columns	number	3	The number of columns in the grid
gutter	number	6	The space between columns and rows
noResultsMessage	string | element	undefined	Customise the "No results" message
noLink	boolean	false	Use a div instead of an a tag for the Gif component, user defines functionality with onGifClick
hideAttribution	boolean	false	Hide the user attribution that appears over a
Gif Events	*	*	see below

Thorough Example

import { throttle } from 'throttle-debounce'
import { renderGrid } from '@giphy/js-components'
import { GiphyFetch } from '@giphy/js-fetch-api'

// create a GiphyFetch with your api key
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')
// create a fetch gifs function that takes an offset
// this will allow the grid to paginate as the user scrolls
const fetchGifs = (offset: number) => {
    // use whatever end point you want,
    // but be sure to pass offset to paginate correctly
    return gf.trending({ offset, limit: 25 })
}

// Creating a grid with window resizing and remove-ability
const makeGrid = (targetEl: HTMLElement) => {
    const render = () => {
        // here is the @giphy/js-components import
        return renderGrid(
            {
                width: innerWidth,
                fetchGifs,
                columns: width < 500 ? 2 : 3,
                gutter: 6,
            },
            targetEl
        )
    }
    const resizeRender = throttle(500, render)
    window.addEventListener('resize', resizeRender, false)
    const remove = render()
    return {
        remove: () => {
            remove()
            window.removeEventListener('resize', resizeRender, false)
        },
    }
}

// Instantiate
const grid = makeGrid(document.querySelector('.grid'))

// To remove
grid.remove()

Carousel

renderCarousel options

property	type	default	description
gifHeight	number	undefined	The height of the gifs and the carousel
gifWidth	number	undefined	The width of the gifs and the carousel (you may want to set Gif.imgClassName to have object-fit: cover to avoid stretching)
fetchGifs	(offset:number) => Promise<GifsResult>	undefined	A function that returns a Promise. Use @giphy/js-fetch-api
gutter	number	6	The space between columns and rows
noResultsMessage	string | element	undefined	Customise the "No results" message
hideAttribution	boolean	false	Hide the user attribution that appears over a
noLink	boolean	false	Use a div instead of an a tag for the Gif component, user defines functionality with onGifClick
Gif Events	*	*	see below

import { renderCarousel } from '@giphy/js-components'
import { GiphyFetch } from '@giphy/js-fetch-api'

// create a GiphyFetch with your api key
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')

// Creating a grid with window resizing and remove-ability
const vanillaJSCarousel = (mountNode: HTMLElement) => {
    renderCarousel(
        {
            gifHeight: 200,
            fetchGifs: (offset: number) => gf.trending({ offset }),
            gutter: 6,
            onGifClick: (gif: IGif) => window.open(gif.url),
        },
        mountNode
    )
}

Gif

Gif props

prop	type	default	description
gif	IGif	undefined	The gif to display
width	number	undefined	The width of the gif
backgroundColor	string	random giphy color	The background of the gif before it loads
hideAttribution	boolean	false	Hide the user attribution that appears over a GIF
noLink	boolean	false	Use a div instead of an a tag for the Gif component, user defines functionality with onGifClick
Gif Events	*	*	see below

import { renderGif } from '@giphy/js-components'
import { GiphyFetch } from '@giphy/js-fetch-api'

// create a GiphyFetch with your api key
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')

const vanillaJSGif = async (mountNode: HTMLElement) => {
    // render a single gif
    const { data: gif1 } = await gf.gif('fpXxIjftmkk9y')
    renderGif({ gif: gif1, width: 300 }, mountNode)
}

Video

Quick and easy way to play video. Just pass the video component a gif object that has a video property. This is true when using { type: 'videos' } in the fetch api type option.

If you want controls for the video player, use the controls property.

Video props

prop	type	default	description
gif	IGif	undefined	The gif to display that contains video data
width	number	undefined	The width of the video
height	number	undefined	The height of the video
controls	boolean	undefined	Show transport controls
hideProgressBar	boolean	undefined	if controls is true, hides progress bar
hideMute	boolean	undefined	if controls is true, hides the mute button
hidePlayPause	boolean	undefined	if controls is true, hides the play/pause button
persistentControls	boolean	undefined	don't hide controls when hovering away
onUserMuted	(muted: boolean) => void	undefined	fired when the user toggles the mute state

import { renderVideo } from '@giphy/js-components'
import { GiphyFetch } from '@giphy/js-fetch-api'

// create a GiphyFetch with your api key
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')

const vanillaJSVideo = async (mountNode: HTMLElement) => {
    // render a video
    const { data: gif1 } = await gf.gif('D068R9Ziv1iCjezKzG')
    renderVideo({ gif: gif1, width: 300, controls: true }, mountNode)
}

Attribution Overlay

If a GIF has an associated user, an overlay with their avatar and display name will appear. This can be hidden with hideAttribution on any of the components.

Gif Events

property	type	description
onGifHover	(gif: IGif, e: Event) => void	fired on desktop when hovered for
onGifVisible	(gif: IGif, e: Event) => void	fired every time the gif is show
onGifSeen	(gif: IGif, boundingClientRect: ClientRect | DOMRect) => void	fired once after the gif loads and when it's completely in view
onGifClick	(gif: IGif, e: Event) => void	fired when the gif is clicked
onGifRightClick	(gif: IGif, e: Event) => void	fired when the gif is right clicked
onGifKeyPress	(gif: IGif, e: Event) => void	fired when the a key is pressed on the gif

To stop fonts from loading set the environment variable GIPHY_SDK_NO_FONTS=true, this is not recommended as it could cause inconsistencies in the ui components