@giphy/react-components v9.5.0

@giphy/react-components

React components, focused on ease-of-use and performance.

The GIPHY React SDK lets you and your users easily access the world’s largest GIF library anywhere on your website. Whether it’s via a comment, forum post, review, chatbot or messenger, adding GIFs to your product is a simple and easy way to boost engagement and user experience.

GIPHY React SDK includes all the same endpoints listed in our Javascript Fetch API:

• Search: Search all Giphy GIFs for a word or phrase. Punctuation will be stripped and ignored.
• Trending Fetch GIFs currently trending online. Hand curated by the Giphy editorial team. The data returned mirrors the GIFs showcased on the Giphy homepage.
• GIF by ID Fetch detailed information about a GIF by ID
• GIFs category and subcategory Fetch GIFs category and subcategory
• Related Fetch related GIFs based on the ID of a GIF
• Random Returns a random single GIF

To try out it out before integrating, click on the code sandbox below. You may have also seen it in action on Google Chrome extention or Facebook Messenger bot.

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.

If React isn’t right for you, check out our other SDK repos that may be a better fit:

• GIPHY JS SDK
• GIPHY SDK for iOS
• GIPHY SDK for Android

Try it out:

Storybook:

storybook UI component explorer.

Grid

Bare Bones Example

See codesandbox for runnable code

import { Grid } from '@giphy/react-components'
import { GiphyFetch } from '@giphy/js-fetch-api'
// 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')

const searchTerm = 'dogs'
// fetch 10 gifs at a time as the user scrolls (offset is handled by the grid)
// if this function changes, change the Grid key to recreate the grid and start over
// see the codesandbox for a runnable example
const fetchGifs = (offset: number) => gf.search(searchTerm, { offset, limit: 10 })
// React Component
ReactDOM.render(<Grid width={800} columns={3} gutter={6} fetchGifs={fetchGifs} key={searchTerm} />, target)

SSR example with next.js

See this codesandbox for an example of SSR with next.js

Carousel

See codesandbox for runnable code.

Or see our storybook UI component explorer.

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

// use @giphy/js-fetch-api to fetch gifs
const gf = new GiphyFetch('your api key')
const searchTerm = 'dogs'
// fetch 10 gifs at a time as the user scrolls (offset is handled by the grid)
// if this function changes, change the Grid key to recreate the grid and start over
// see the codesandbox for a runnable example
const fetchGifs = (offset: number) => gf.search(searchTerm, { offset, limit: 10 })
// React Component
ReactDOM.render(<Carousel gifHeight={200} gutter={6} fetchGifs={fetchGifs} key={searchTerm} />, target)

Gif

Displays a single GIF. The building block of the Grid and Carousel. If you want to build a custom layout component, using this will make it easy to do so.

Gif props

See codesandbox for runnable code

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

// 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 single gif
const { data } = await gf.gif('fpXxIjftmkk9y')
// React Component
ReactDOM.render(<Gif gif={data} width={300} />, target)

Search Experience

The search experience is built on a search bar and a separate visual component that can display content, which can be a Grid or Carousel, or a custom component that can fetch and render an array of IGif objects. To create the search experience, we use React.Context to set up communication between the search bar and other components by defining them as children of a SearchContextManager. We recommend using the SuggestionBar to display trending searches and enable username searches when a user searches by username (e.g. @nba).

See codesandbox for runnable code

import {
    Grid, // our UI Component to display the results
    SearchBar, // the search bar the user will type into
    SearchContext, // the context that wraps and connects our components
    SearchContextManager, // the context manager, includes the Context.Provider
    SuggestionBar, // an optional UI component that displays trending searches and channel / username results
} from '@giphy/react-components'

// the search experience consists of the manager and its child components that use SearchContext
const SearchExperience = () => (
    <SearchContextManager apiKey={webSDKKey}>
        <Components />
    </SearchContextManager>
)

// define the components in a separate function so we can
// use the context hook. You could also use the render props pattern
const Components = () => {
    const { fetchGifs, searchKey } = useContext(SearchContext)
    return (
        <>
            <SearchBar />
            <SuggestionBar />
            {/** 
                key will recreate the component, 
                this is important for when you change fetchGifs 
                e.g. changing from search term dogs to cats or type gifs to stickers
                you want to restart the gifs from the beginning and changing a component's key does that 
            **/}
            <Grid key={searchKey} columns={3} width={800} fetchGifs={fetchGifs} />
        </>
    )
}

SearchContextManager

This component manages the SearchContext that the child components access.

It has a few initialization props:

Searchbar

An input field used in the Search Experience.

SearchContext

The SearchContext manages the state of the search experience. The props below are all you need to configure your UI component. See (Search Experience)#search-experience. It should use searchKey as its key, so when we have a new search, the old content is removed. And it will need a fetchGifs to initiate the first fetch and for subsequent infinite scroll fetches

SearchTheme

Theme is passed to the SearchContextManager

SuggestionBar

Display scrolling trending searches and username search. When clicking a trending search term, the search input will be populated with that term and the search will be fetched and rendered.

If a user types a username into the search bar such as @nba, a username search will done and the all the channels that match will be displayed in the suggestion bar. When clicking a username, the search bar will go into username search mode.

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.

Here are the components in action in our storybook

Video props

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

// 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')

const { data } = await gf.gif('D068R9Ziv1iCjezKzG')
// React Component
ReactDOM.render(<Video gif={data} width={300} controls />, target)

EmojiVariationsList

This component is designed to display a list of variations for a given emoji.

Here are the components in action in our storybook

Example:

import React, { useState } from 'react'
import ReactDOM from 'react-dom'
import { GiphyFetch } from '@giphy/js-fetch-api'
import { EmojiVariationsList, Grid } from '@giphy/react-components'
import type { GifID, IGif } from '@giphy/js-types'

// 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')

const fetchDefaultVariations = (offset: number) => gf.emojiDefaultVariations({ offset })
const fetchVariations = (id: GifID) => gf.emojiVariations(id)

export function Example() {
    const [gif, setGif] = useState<IGif | null>(null)
    return (
        <>
            {gif ? <EmojiVariationsList fetchVariations={fetchVariations} gif={gif} gifHeight={100} /> : null}
            <Grid
                columns={3}
                fetchGifs={fetchDefaultVariations}
                hideAttribution={true}
                noLink={true}
                onGifClick={setGif}
                width={400}
            />
        </>
    )
}

ReactDOM.render(<Example />, target)

GifOverlay

The overlay prop, available on all components allows you to overlay a gif with a custom UI and respond to hover events (desktop only).

Overlay props

See codesandbox for runnable code

/* css for overlay */
.overlay {
    position: absolute;
    left: 0;
    top: 0;
    right: 0;
    bottom: 0;
    background: rgba(0, 255, 0, 0.3);
    display: flex;
    color: white;
    justify-content: center;
    align-items: center;
}

// Overlay component gets GifOverlayProps
const Overlay = ({ gif, isHovered }: GifOverlayProps) => {
    return <div className="overlay">{isHovered ? gif.id : ''}</div>
}

// React component
ReactDOM.render(<Carousel gifHeight={200} fetchGifs={fetchGifs} overlay={Overlay} />, target)

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. If you provide your own overlay, attribution will be hidden automatically

Loader Config

If you want to prefetch network requests before the loader appears in Grids and Carousels, you can do so by configuring loaderConfig. This config is actually just the options that are passed to IntersectionObserver, which is in charge of monitoring the Loader and firing an event when it appears on screen. This is configured in a util component called Observer

Gif Events

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