@giphy/react-components (2024)

@giphy/react-components (1)

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:

Try it out:

@giphy/react-components (2)

Storybook:

storybook UI component explorer.

Grid

proptypedefaultdescription
widthnumberundefinedThe width of the grid
fetchGifs(offset:number) => Promise<GifsResult>undefinedA function that returns a Promise. Use @giphy/js-fetch-api
columnsnumber3The number of columns in the grid
gutternumber6The space between columns and rows
borderRadiusnumber4a border radius applied to Gif Components making the corners rounded
noResultsMessagestring or JSX.ElementundefinedCustomize the "No results" message
loaderElementTypeundefinedCustomize the loader, the default is the GIPHY brand loader
noLinkbooleanfalseUse a div instead of an a tag for the Gif component, user defines functionality with onGifClick
hideAttributionbooleanfalseHide the user attribution that appears over a GIF
loaderConfigIntersectionObserverInitundefinedEnables configuring the loader to fetch sooner than when just onscreen, allowing for smoother scrolling
Gif Events**see below

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 exampleconst fetchGifs = (offset: number) => gf.search(searchTerm, { offset, limit: 10 })// React ComponentReactDOM.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

proptypedefaultdescription
gifHeightnumberundefinedThe height of the gifs and the carousel
gifWidthnumberundefinedThe 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>undefinedA function that returns a Promise. Use @giphy/js-fetch-api
gutternumber6The space between columns and rows
borderRadiusnumber4a border radius applied to Gif Components making the corners rounded
noResultsMessagestring or JSX.ElementundefinedCustomize the "No results" message
noLinkbooleanfalseUse a div instead of an a tag for the Gif component, user defines functionality with onGifClick
hideAttributionbooleanfalseHide the user attribution that appears over a GIF
loaderConfigIntersectionObserverInitundefinedEnables configuring the loader to fetch sooner than when just onscreen, allowing for smoother scrolling
Gif Events**see below

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 gifsconst 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 exampleconst fetchGifs = (offset: number) => gf.search(searchTerm, { offset, limit: 10 })// React ComponentReactDOM.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

proptypedefaultdescription
gifIGifundefinedThe gif to display
widthnumberundefinedThe width of the gif
borderRadiusnumber4a border radius making the corners rounded
backgroundColorstringrandom giphy colorThe background of the gif before it loads
hideAttributionbooleanfalseHide the user attribution that appears over a GIF
noLinkbooleanfalseUse a div instead of an a tag for the Gif component, user defines functionality with onGifClick
overlay(props: GifOverlayProps):ReactType => {}undefinedsee below
Gif Events**see below

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 gifconst { data } = await gf.gif('fpXxIjftmkk9y')// React ComponentReactDOM.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 SearchContextconst 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 patternconst 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:

proptypedefaultdescription
apiKeystringundefinedYour web SDK key. Use a separate key for every platform (Android, iOS, Web)
initialTermstring''Advanced usage a search term to fetch and render when the component is mounted
shouldDefaultToTrendingbooleantruewhen there is no search term, fetch trending (includes options that are relevant e.g. limit, type)
shouldFetchChannelsbooleantrueFetch channels while the term changes, enabling them to be displayed in a SuggestionBar. If the search term is @term and a channel is found that matches, the search bar will display in channel mode
themeSearchThemedefault themeA few theming options such as search bar height and dark or light mode
optionsSearchOptionsundefinedSearch options that will be passed on to the search request

Searchbar

An input field used in the Search Experience.

proptypedefaultdescription
placeholderstringSearch GIPHYThe text displayed when no text is entered
themeSearchThemedefault themeSee (SearchTheme)[#searchtheme]
clearbooleanfalseAdvanced useage - clears the input but will leave the term in the SearchContext

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

proptypedefaultdescription
searchKeystringundefinedA unique id of the current search, used as a React key to refresh the Grid
isFocusedbooleanfalsewhether or not the search input has focus
currentChannelsIChannel[][]an array of channels that were found with the current search term
fetchGifs(offset: number) => Promise<GifsResult>default search fetchThe search request passed to the UI component

SearchTheme

Theme is passed to the SearchContextManager

proptypedefaultdescription
modedark | lightlightdark or light
searchbarHeightnumber42Height of the search bar
smallSearchbarHeightnumber35Height of the search bar when matching mobile media query

SuggestionBar

Display scrolling trending searches and username search. When clicking a trending search term, the search input will bepopulated 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

proptypedefaultdescription
gifIGifundefinedThe gif to display that contains video data
widthnumberundefinedThe width of the video
heightnumberundefinedThe height of the video
controlsbooleanundefinedShow transport controls
hideProgressBarbooleanundefinedif controls is true, hides progress bar
hideMutebooleanundefinedif controls is true, hides the mute button
hidePlayPausebooleanundefinedif controls is true, hides the play/pause button
persistentControlsbooleanundefineddon't hide controls when hovering away
ccEnabledbooleanfalseif true, show captions
ccLanguagestring'en'the closed caption language
onUserMuted(muted: boolean) => voidundefinedfired when the user toggles the mute state
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 ComponentReactDOM.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

proptypedefaultdescription
fetchVariations(gifId: GifID) => Promise<NonPaginatedGifsResult>undefinedThe async callback that should return emoji variations. Use @giphy/js-fetch-api
gifIGifundefinedSpecifies for which gif to display variations
gifHeightnumberundefinedThe height of the gifs in the list
gifWidthnumberundefinedThe width of the gifs in the list
backgroundColorstring'#2e2e2e'Set the background color for the list
dividerColorstring'#4e4e4e'Set the color for the divider
gutternumber6The space between the gifs
loaderElementTypeundefinedSpecifies the loader
noLinkbooleanfalseUse a div instead of an a tag for the Gif component, user defines functionality with onGifClick
onVariationsFetched(gifs: IGif[]) => voidundefinedThe callback that will be called when variations are fetched
hideAttributionbooleanfalseHide the user attribution that appears over a GIF
GifPropsGifPropsundefinedProps applied to the Gif element
Gif Events**see below

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

proptypedefaultdescription
gifIGifundefinedThe gif that is being displayed
isHoveredbooleanfalseThe current hover state

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 GifOverlayPropsconst Overlay = ({ gif, isHovered }: GifOverlayProps) => { return <div className="overlay">{isHovered ? gif.id : ''}</div>}// React componentReactDOM.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

proptypedescription
onGifVisible(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => voidfired every time the gif is show
onGifSeen(gif: IGif, boundingClientRect: ClientRect &#124; DOMRect) => voidfired once after the gif loads and when it's completely in view
onGifClick(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => voidfired when the gif is clicked
onGifRightClick(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => voidfired when the gif is right clicked
onGifKeyPress(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => voidfired 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

@giphy/react-components (2024)
Top Articles
Latest Posts
Recommended Articles
Article information

Author: Chrissy Homenick

Last Updated:

Views: 6133

Rating: 4.3 / 5 (54 voted)

Reviews: 85% of readers found this page helpful

Author information

Name: Chrissy Homenick

Birthday: 2001-10-22

Address: 611 Kuhn Oval, Feltonbury, NY 02783-3818

Phone: +96619177651654

Job: Mining Representative

Hobby: amateur radio, Sculling, Knife making, Gardening, Watching movies, Gunsmithing, Video gaming

Introduction: My name is Chrissy Homenick, I am a tender, funny, determined, tender, glorious, fancy, enthusiastic person who loves writing and wants to share my knowledge and understanding with you.