@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