react-giphy-selector

A search and select React.JS component for picking the perfect gif from GIPHY.

This component is highly-customizable and only provides basic styling out-of-box. The example above includes simple customization to a few elements. You can view this example in /example/src.

Table of Contents

• Installation
• Usage

Installation

You just install react-giphy-selector the good ole' fashion way through NPM:

npm install --save react-giphy-selector

Usage

This package exports the Selector React component and then two helper enums:

import {Selector, ResultSort, Rating} from "react-giphy-selector";

• Selector
• Rating
• ResultSort

Selector

The selector component contains all of the search, display, and selection logic. The only required properties are apiKey and onGifSelected.

<Selector
	apiKey={'myKey'}
	onGifSelected={this.saveGif} />

That said, there are a bunch of props that allow you to make this component your own. Note: the ? included at the end of a property name denotes it as optional.

• apiKey: string: Your Giphy Project API Key.
• onGifSelected: (gifObject: IGifObject) => void: The function to fire when a gif search result has been selected. The IGifObject represents the full GIF Object returned via the Giphy API.
• queryFormAutoFocus?: boolean: If you want or not the search field to be focused when the component mounts.
• preloadTrending?: boolean: If you want or not the component to be prepopulated with the trending gifs when it appears.
• rating?: Rating: The maximum rating you want to allow in your search results. Use the exported Rating enum for help. Default: Rating.G.
• sort?: ResultSort: The sort order of the search results. Use the helper enum ResultSort. Default: ResultSort.Relevant.
• limit?: number: The number of results to return. Default: 20.
• suggestions?: string[]: An array containing one-click searches to make it easy for your user. Will not show suggestions section if none are passed. Default: [].
• queryInputPlaceholder?: string: The placeholder text for the search bar text input. Default 'Enter search text'.
• resultColumns?: number: The number of columns to divide the search results into. Default: 3.
• showGiphyMark?: boolean: Indicates whether to show the "powered by Giphy" mark in the selector. This is required when using a Giphy Production API Key. Default: true.

Styling your Selector

There are a bunch of props to help you customize the style of the the selector. Both the className and the style methods are available. react-giphy-selector is very intentionally unopinionated about how exactly each section of the selector should look. Instead, the package offers a lot of customization and flexibility through the props below.

The images below will help you understand the nomenclature of the components:

Here are all the props available for styling the component:

• containerClassName?: string: Additional className for the main container of the component.
• containerStyle?: object: A style object to add to the main div container. No default applued.
• queryFormClassName?: string: Additional className for the query form section of the component. You can find the default style applied in src/components/QueryForm.css.
• queryFormInputClassName?: string: Additional className for the text input in the query form. You can find the default style applied in src/components/QueryForm.css.
• queryFormSubmitClassName?: string: Additional className for the submit button in the query form. You can find the default style applied in src/components/QueryForm.css.
• queryFormStyle?: object: A style object to add to the query form style. You can find the default style applied in src/components/QueryForm.css.
• queryFormInputStyle?: object: A style object to add to the text input in the query form. You can find the default style applied in src/components/QueryForm.css.
• queryFormSubmitStyle?: object: A style object to add to the submit button in the query form. You can find the default style applied in src/components/QueryForm.css.
• queryFormSubmitContent?: string or Component: You can pass in a string or your own component to render inside the submit button in the query form. This allows you to pass in things like custom icons. Default: 'Search'.
• searchResultsClassName?: string: Additional className for the search results component. You can find the default style in src/components/SearchResults.css.
• searchResultsStyle?: object: A style object to the add to the search results container. You can find the default style in src/components/SearchResults.css.
• searchResultClassName?: string: Additional className to add to a search result. Search results are a elements. You can find the default style in src/components/SearchResult.css.
• searchResultStyle?: object: A style object to add to a search result. Search results are a elements. You can find the default style in src/components/SearchResult.css.
• suggestionsClassName?: string: Additional className to add to the suggestions container. You can find the default style in src/components/Suggestions.css.
• suggestionsStyle?: object: A style object to add to the suggestions container. You can find the default style in src/components/Suggestions.css.
• suggestionClassName?: string: Additional className to add to a suggestion. This is an a element. You can find the default style in src/components/Suggestion.css.
• suggestionStyle?: object: A style object to add to a suggestion. This is an a element. You can find the default style in src/components/Suggestion.css.
• loaderClassName?: string: Additional className to add to the loader container. You can find the default style in src/components/Selector.css.
• loaderStyle?: object: A style object to add to the loader container. You can find the default style in src/components/Selector.css.
• loaderContent?: string or Component: You can pass in a string or customer component to display when results are loading. Default 'Loading'....
• searchErrorClassName?: string: Additional className to add to the error message shown on broken searches. You can find the default style in src/components/Selector.css.
• searchErrorStyle?: object: A style object to add to the error message shown on broken searches. You can find the default style in src/components/Selector.css.
• footerClassName?: string: Additional className to add to footer of selector. You can find the default style in src/components/Selector.css.
• footerStyle?: object: A style object to add to footer of selector. You can find the default style in src/components/Selector.css.

If you have a cool style you'd like to share, please make an issue.

Rating

The Rating enum contains all the possible ratings you can limit searches to:

Rating.Y
Rating.G
Rating.PG
Rating.PG13
Rating.R

ResultSort

The ResultSort enum contains the different sort methods supported by the Giphy API.

ResultSort.Recent // ordered by most recent
ResultSort.Relevant // ordered by relevance

License

Copyright © 2015-2021 Iacopo Carraro

This code is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License (CC BY-NC-SA 4.0).

This means the code is source available to you, but is not open source, due to the following terms of the CC BY-NC-SA 4.0 license:

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.

NonCommercial — You may not use the material for commercial purposes.

ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

This code is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.