api.md

API Reference

• GiphySDK
• GiphyDialog
• GiphyMediaView
• GiphyVideoView
• GiphyVideoManager
• GiphyGridView
• GiphyContent
• GiphyTheme

GiphyFlutterSDK

Contains methods for configuring basic parameters, such as API keys.

</> configure: void configure({required String apiKey, bool verificationMode = false})

Configure basic settings of GIPHY SDK.

Options

Option	Description	Type	Default	Platform
apiKey	Android or iOS SDK key. Please remember, you should use a separate key for every platform (Android, iOS) you add our SDKs to.	string	None	✅ Android ✅ iOS
videoCacheMaxBytes	A number that defines the video cache size for ExoPlayer on the Android platform. Note: If videoCacheMaxBytes is 0, the cache initialization will be skipped, and Giphy Clips will not work. You may want to skip this setting if you use another version of ExoPlayer that is not compatible with the Giphy SDK but still wish to receive gifs from Giphy.	double	100 * 1024 * 1024	✅ Android ❌ iOS

Example

import 'package:giphy_flutter_sdk/giphy_flutter_sdk.dart';

String? apiKey;
if (Platform.isAndroid) {
  apiKey = '*************'; // Android SDK key
} else if (Platform.isIOS) {
  apiKey = '*************'; // iOS SDK key
} else {
  throw Exception('Unsupported platform');
}
if (apiKey.isEmpty) {
  throw Exception('API key for the platform is null or not configured');
}
GiphyFlutterSDK.configure(apiKey: apiKey);

GiphyDialog

Singleton, which provides pre-built templates that handle the entirety of the GIPHY experience.

</> configure: configure({GiphySettings? settings}

Configure the GiphyDialog view and behavior.

Options

Option	Description	Type	Default	Platform
clipsPreviewRenditionType	Certain renditions (cases of the GiphyRendition enum) are not available for Clips. As a result, if you set the renditionType property of the GiphyDialog to an unsupported rendition type, clips previews may not play back correctly in the grid. To account for this limitation, we created this property specifically to work with clips.	GiphyClipsRendition	.FixedWidth	✅ Android ✅ iOS
confirmationRenditionType	A rendition type for the confirmation screen.	GiphyRendition	.Original	✅ Android ❌ iOS
enableDynamicText	Allows to create animated text results for search queries where there are no matching results in GIPHY's library. Learn more	bool	false	✅ Android ✅ iOS
fileFormat	A file format for the grid.	GiphyFileFormat	.webp	✅ Android ✅ iOS
mediaTypeConfig	Type(s) of content to be displayed in the dialog. Note: Emoji only is not available for the carousel layout option.	List<GiphyContentType>	Expand [.recents, .gif, .sticker, .text, .emoji]	✅ Android ✅ iOS
rating	A specific content rating for the search results.	GiphyRating	.pg13	✅ Android ✅ iOS
renditionType	A rendition type for the grid.	GiphyRendition	.fixedWidth	✅ Android ✅ iOS
selectedContentType	The default Giphy Content-Type.	GiphyContentType	.gif	✅ Android ✅ iOS
showCheckeredBackground	Enable/disable the checkered background for stickers and text media type.	bool	false	✅ Android ❌ iOS
showConfirmationScreen	Show a secondary confirmation screen when the user taps a GIF, which shows a larger rendition of the asset. This confirmation screen is only available for GiphyDirection.vertical mode - this property will be ignored if the layout is GiphyDirection.horizontal.	bool	false	✅ Android ✅ iOS
showSuggestionsBar	Show/hide a suggestions bar.	bool	true	✅ Android ❌ iOS
stickerColumnCount	For carousel layouts, we provide the option to set the number of columns for stickers and text. We recommend using 3 columns for blurred mode.	int	3	✅ Android ✅ iOS
theme	Adjust the GiphyDialog theme	GiphyTheme	.automatic	✅ Android ✅ iOS

</> show: void show()

Show the Giphy Dialog.

</> hide: void hide()

Hide the Giphy Dialog.

Supported events 🔔

The GiphyMediaSelectionListener is an abstract class designed to handle events from the Giphy dialog. To use GiphyMediaSelectionListener, implement this abstract class in your widget state. The implementation requires defining two methods:

• onMediaSelect void onMediaSelect(GiphyMedia media)
• onDismiss void onDismiss()

which handle media selection and dialog dismissal, respectively.

Example

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:giphy_flutter_sdk/dto/giphy_media.dart';
import 'package:giphy_flutter_sdk/giphy_dialog.dart';
import 'package:giphy_flutter_sdk/giphy_flutter_sdk.dart';
import 'config.dart' as config;

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> implements GiphyMediaSelectionListener {
  @override
  void initState() {
    super.initState();
    initPlatformState();
  }

  @override
  void dispose() {
    super.dispose();
  }

  void initPlatformState() {
    try {
      String? apiKey;
      if (Platform.isAndroid) {
        apiKey = config.androidGiphyApiKey;
      } else if (Platform.isIOS) {
        apiKey = config.iOSGiphyApiKey;
      } else {
        throw Exception('Unsupported platform');
      }
      if (apiKey.isEmpty) {
        throw Exception('API key for the platform is null or not configured');
      }
      GiphyFlutterSDK.configure(apiKey: apiKey);
      GiphyDialog.instance.addListener(this);
    } catch (e) {
      print(e);
    }
  }

  final List<GiphyMedia> _mediaList = [];

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
        home: Scaffold(
      appBar: AppBar(
        title: const Text('Giphy Media Selection'),
      ),
      body: ListView.builder(
        itemCount: _mediaList.length + 1,
        itemBuilder: (context, index) {
          if (index == 0) {
            return ListTile(
              title: const Text('Show Dialog'),
              onTap: () {
                _showGiphyDialog();
              },
            );
          }
          final mediaIndex = index - 1;
          return Image(
              image: NetworkImage(
                  _mediaList[mediaIndex].images.original!.gifUrl!));
        },
      ),
    ));
  }

  void _showGiphyDialog() {
    GiphyDialog.instance.show();
  }

  @override
  void onMediaSelect(GiphyMedia media) {
    setState(() {
      _mediaList.insert(0, media);
    });
  }

  @override
  void onDismiss() {
    print("Giphy dialog dismissed");
  }
}

Troubleshooting

On Android, the dialog requires using FlutterFragmentActivity. In your project's MainActivity, which is in the android folder, you'll need to replace:

import io.flutter.embedding.android.FlutterActivity

class MainActivity: FlutterActivity()

with:

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity()

GiphyMediaView

Designed to render GiphyMedia objects.

Props

Prop	Description	Type	Default	Platform
autoPlay	A boolean flag indicating whether or not the animation should start automatically when mounted.	bool	true	✅ Android ✅ iOS
media	Pass a GiphyMedia object to display content.	GiphyMedia	null	✅ Android ✅ iOS
mediaId	Pass a GiphyMedia object ID to display content.	String	null	✅ Android ✅ iOS
renditionType	A rendition type for the view.	GiphyRendition	.fixedWidth	✅ Android ✅ iOS
resizeMode	Determines how to resize the image when the frame doesn't match the raw image dimensions.	GiphyResizeMode	.Cover	✅ Android ✅ iOS
showCheckeredBackground	Enable/disable the checkered background for stickers and text media type.	bool	true	✅ Android ❌ iOS
onError	A callback function that will be called when an error occurs whilst attempting to render media.	Function(String description)? onError	null	✅ Android ✅ iOS

Methods (Imperative API)

GiphyMediaView widget is controlled via the controller: an instance of GiphyMediaViewController.

Method	Description	Type	Platform
pause	Pauses the animation.	Future<void>	✅ Android ✅ iOS
resume	Resumes the paused animation.	Future<void>	✅ Android ✅ iOS

⚠️ GiphyMediaView and GIPHY Animated Text

If you use GIPHY Animated Text in your integration (media.isDynamic == true), please note that GiphyMediaView does not support it. For more information, please refer to this article.

Example

• Basic usage

You can update the example above

AspectRatio(
  aspectRatio: _mediaList[mediaIndex].aspectRatio,
  child: GiphyMediaView(
    media: _mediaList[mediaIndex],
    autoPlay: true,
    renditionType: GiphyRendition.fixedWidth));

• Imperative API

class GiphyMediaScreen extends StatefulWidget {
  const GiphyMediaScreen({super.key});

  @override
  _GiphyMediaScreenState createState() => _GiphyMediaScreenState();
}

class _GiphyMediaScreenState extends State<GiphyMediaScreen> {
  GiphyMediaViewController? controller;

  @override
  void initState() {
    super.initState();
    controller = GiphyMediaViewController();
  }

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Row(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              ElevatedButton(
                onPressed: () {
                  controller?.pause();
                },
                child: const Text('Pause'),
              ),
              const SizedBox(width: 10),
              ElevatedButton(
                onPressed: () {
                  controller?.resume();
                },
                child: const Text('Resume'),
              ),
            ],
          ),
          AspectRatio(
              aspectRatio: 1,
              child: GiphyMediaView(
                controller: controller,
                mediaId: 'CnLRoQneO2kWHuRg7g',
                autoPlay: true,
                resizeMode: GiphyResizeMode.contain,
              )),
        ],
      ),
    );
  }
}

GiphyVideoView

Note: If you use GIPHY Clips on the Android platform, you need to set up clips integration before working with the GiphyVideoView component.

Similar to the GiphyMediaView which works for GIFs, Stickers, and Text, the GiphyVideoView is a component that makes it easy to play back GiphyMedia clips video assets. The GiphyVideoView will only work for GiphyMedia where the isVideo property is true.

Note: GiphyVideoView has no advanced features for playback, volume, and buffering control. If you need some advanced features, you can easily integrate clips with other more advanced video players.

Props

Prop	Description	Type	Default	Platform
autoPlay	Set it to true to start the video automatically.	bool	false	✅ Android ✅ iOS
media	Pass a GiphyMedia object to display content.	GiphyMedia	None	✅ Android ✅ iOS
mediaId	Pass a GiphyMedia object ID to display content.	String	None	✅ Android ✅ iOS
muted	Set to true or false to mute or unmute the player.	bool	false	✅ Android ✅ iOS
onError	A callback function that will be called when an error occurs whilst attempting to play media.	Function(String description)? onError	null	✅ Android ✅ iOS
onMute	A callback function that will be called when media is muted.	Function()? onMute	null	✅ Android ✅ iOS
onPlaybackStateChanged	A callback function that will be called when playback state changes.	Function(GiphyVideoViewPlaybackState state)? onPlaybackStateChanged	null	✅ Android ✅ iOS
onUnmute	A callback function that will be called when media is unmuted.	Function()? onUnmute	null	✅ Android ✅ iOS

Example

child: AspectRatio(
  aspectRatio: _mediaList[index].aspectRatio,
  child: _mediaList[index].isVideo
      ? GiphyVideoView(
          media: _mediaList[index],
          autoPlay: true,
          muted: false,
        )
      : _GiphyMediaView(
          media: _mediaList[index],
          autoPlay: true,
          renditionType: GiphyRendition.fixedWidth,
        ),
),

GiphyVideoManager

The module that allows you to control GiphyVideoView players.

</> muteAll: void muteAll()

Mute active GiphyVideoView player.

</> pauseAll: void pauseAll()

Pause active GiphyVideoView player.

</> resume: void resume()

Resume the playback.

Example

GiphyVideoManager.instance.muteAll();
GiphyVideoManager.instance.pauseAll();
GiphyVideoManager.instance.resume();

GiphyGridView

Customizable implementation of a Giphy Grid only.

Props

Prop	Description	Type	Default	Platform
cellPadding	Spacing between rendered GIFs.	double Note: On iOS, only values between 0 and 11 inclusive are supported.	0	✅ Android ✅ iOS
clipsPreviewRenditionType	Certain renditions (cases of the GiphyRendition enum) are not available for Clips. As a result, if you set the renditionType property of the GiphyGridView to an unsupported rendition type, clips previews may not play back correctly in the grid. To account for this limitation, we created this property specifically to work with clips.	GiphyClipsRendition	.fixedWidth	✅ Android ✅ iOS
content	A GiphyContentRequest object describing a content request to the Giphy API.	GiphyContentRequest	None	✅ Android ✅ iOS
disableEmojiVariations	If true, the emoji variations drawer is not rendered.	bool	false	✅ Android ✅ iOS
fixedSizeCells	Display content in equally sized cells (for stickers only).	bool	false	✅ Android ✅ iOS
onContentUpdate	A callback function that will be called when a content is updated.	Function(int resultCount)? onContentUpdate	null	✅ Android ✅ iOS
onMediaSelect	A callback function that will be called when a media is selected.	Function(GiphyMedia media)? onMediaSelect	null	✅ Android ✅ iOS
onScroll	A callback function that will be called when a grid is being scrolled.	Function(double offset)? onScroll	null	✅ Android ✅ iOS
orientation	Tells the scroll direction of the grid. (e.g. GiphyDirection.horizontal, GiphyDirection.vertical)	GiphyDirection	.vertical	✅ Android ✅ iOS
renditionType	A rendition type for the grid.	GiphyRendition	.fixedWidth	✅ Android ✅ iOS
spanCount	Number of lanes in the grid.	int	Depends on orientation and content type	✅ Android ✅ iOS
showCheckeredBackground	Show/Hide checkered background for stickers in the grid.	bool	false	✅ Android ❌ iOS
theme	Adjust the GiphyGridView theme	GiphyTheme	.automatic	✅ Android ✅ iOS

Example

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    GiphyFlutterSDK.configure(apiKey: '*************');
  }

  Widget build(BuildContext context) {
    return MaterialApp(
        home: Scaffold(
      appBar: AppBar(
        title: const Text('Giphy example app'),
        backgroundColor: Colors.white,
        foregroundColor: Colors.black,
      ),
      body: Column(children: <Widget>[
        Expanded(
          child: GiphyGridView(
            content: const GiphyContentRequest(
                mediaType: GiphyMediaType.gif,
                requestType: GiphyContentRequestType.search,
                searchQuery: "cat"),
            onMediaSelect: (GiphyMedia media) {
              print("Selected media:${media.id}");
            },
          ),
        )
      ]),
    ));
  }

GiphyContent

Provides methods to describe a content request to the Giphy API.

</> search: GiphyContentRequest.search({required GiphyMediaType mediaType, GiphyRating rating = GiphyRating.pg13, required String searchQuery})

Options

Option	Description	Type	Default	Platform
mediaType	A media type that should be loaded (e.g. GiphyMediaType.gif)	GiphyMediaType	.gif	✅ Android ✅ iOS
rating	Filter query results by specific content rating	GiphyRating	.pg13	✅ Android ✅ iOS
searchQuery	A custom search input (e.g. cats)	String	null	✅ Android ✅ iOS

</> trending: GiphyContentRequest.trending({required GiphyMediaType mediaType,GiphyRating rating = GiphyRating.pg13})

Options

Option	Description	Type	Default	Platform
mediaType	A media type that should be loaded (e.g. GiphyMediaType.gif)	GiphyMediaType	.gif	✅ Android ✅ iOS
rating	Filter query results by specific content rating	GiphyRating	.pg13	✅ Android ✅ iOS

</> trendingGifs: GiphyContentRequest.trendingGifs({GiphyRating rating = GiphyRating.pg13})

Options

Option	Description	Type	Default	Platform
rating	Filter query results by specific content rating	GiphyRating	.pg13	✅ Android ✅ iOS

</> trendingStickers: GiphyContentRequest.trendingStickers({GiphyRating rating = GiphyRating.pg13})

Options

Option	Description	Type	Default	Platform
rating	Filter query results by specific content rating	GiphyRating	.pg13	✅ Android ✅ iOS

</> trendingText: GiphyContentRequest.trendingText({GiphyRating rating = GiphyRating.pg13})

Options

Option	Description	Type	Default	Platform
rating	Filter query results by specific content rating	GiphyRating	.pg13	✅ Android ✅ iOS

</> recents: GiphyContentRequest.recents()

Description

GIFs that are selected by the user are automatically added to the recents tab, which is only displayed if the user has previously picked a gif.

Users can remove gifs from recents with a long-press on the GIF in the recents grid.

</> emoji: GiphyContentRequest.emoji()

</> animate: GiphyContentRequest.animate(String input)

Options

Option	Description	Type	Default	Platform
input	A custom search input (e.g. cats)	String	None	✅ Android ✅ iOS

Learn more

Example

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    GiphyFlutterSDK.configure(apiKey: '*************');
  }

  Widget build(BuildContext context) {
    return MaterialApp(
        home: Scaffold(
      appBar: AppBar(
        title: const Text('Giphy example app'),
        backgroundColor: Colors.white,
        foregroundColor: Colors.black,
      ),
      body: Column(children: <Widget>[
        Expanded(
          child: GiphyGridView(
            content: GiphyContentRequest.trendingGifs(),
            onMediaSelect: (GiphyMedia media) {
              print("Selected media:${media.id}");
            },
          ),
        )
      ]),
    ));
  }

GiphyTheme

The GIPHY SDK offers three pre-defined themes presets:

• automatic
• dark
• light

Example

// Configure API keys
...
GiphyFlutterSDK.configure(apiKey: '*************');
...

// Adjust GiphyDialog theme
GiphySettings _settings = const GiphySettings();
GiphyDialog.instance
        .configure(settings: _settings.copyWith(theme: GiphyTheme.dark()));


// Adjust GiphyGridView theme
GiphyGridView(
  content: GiphyContentRequest.trendingStickers(),
  theme: GiphyTheme.dark()
)

To achieve more extensive customization, you can extend any preset and override specific settings according to your requirements. The theme schemas can be found at the following links:

• iOS Theme Schema
• Android Theme Schema

Example

final GiphyTheme _theme = GiphyTheme.fromPreset(
  preset: GiphyThemePreset.dark,
  backgroundColor: const Color(0xFF373d48),
  defaultTextColor: const Color(0xFFB0BEC5));

// Configure API keys
...
GiphyFlutterSDK.configure(apiKey: '*************');
...

// Adjust GiphyDialog theme
GiphySettings _settings = const GiphySettings();
GiphyDialog.instance
  .configure(settings: _settings.copyWith(theme: _theme));


// Adjust GiphyGridView theme
GiphyGridView(
  content: GiphyContentRequest.trendingStickers(),
  theme: _theme
)

Theme Options

Option	Type	Platform
avatarPlaceholderColor	Color	❌ Android ✅ iOS
backgroundColor	Color	✅ Android ✅ iOS
backgroundColorForLoadingCells	Color	❌ Android ✅ iOS
cellCornerRadius	double	❌ Android ✅ iOS
confirmationBackButtonColor	Color	✅ Android ✅ iOS
confirmationSelectButtonColor	Color	✅ Android ✅ iOS
confirmationSelectButtonTextColor	Color	✅ Android ✅ iOS
confirmationViewOnGiphyColor	Color	✅ Android ✅ iOS
defaultTextColor	Color	✅ Android ✅ iOS
dialogOverlayBackgroundColor	Color	✅ Android ❌ iOS
emojiDrawerGradientBottomColor	Color	✅ Android ✅ iOS
emojiDrawerGradientTopColor	Color	✅ Android ✅ iOS
emojiDrawerScrollIndicatorStyle	IndicatorStyle	❌ Android ✅ iOS
emojiDrawerSeparatorColor	Color	✅ Android ✅ iOS
fixedSizeCells	bool	❌ Android ✅ iOS
handleBarColor	Color	✅ Android ✅ iOS
keyboardAppearance	GiphyKeyboardAppearance	❌ Android ✅ iOS
preset	GiphyThemePreset	✅ Android ✅ iOS
retryButtonBackgroundColor	Color	✅ Android ❌ iOS
retryButtonTextColor	Color	✅ Android ❌ iOS
searchBackButtonColor	Color	✅ Android ✅ iOS
searchBarBackgroundColor	Color	✅ Android ✅ iOS
searchBarCornerRadius	double	❌ Android ✅ iOS
searchBarPadding	double	❌ Android ✅ iOS
searchPlaceholderTextColor	Color	✅ Android ✅ iOS
searchTextColor	Color	✅ Android ✅ iOS
showSuggestionsBar	bool	❌ Android ✅ iOS
stickerBackgroundColor	Color	❌ Android ✅ iOS
suggestionCellBackgroundColor	Color	✅ Android ✅ iOS
suggestionCellTextColor	Color	✅ Android ✅ iOS
tabBarBackgroundAlpha	number	❌ Android ✅ iOS
tabBarSwitchDefaultColor	Color	✅ Android ✅ iOS
tabBarSwitchSelectedColor	Color	✅ Android ✅ iOS
usernameColor	Color	✅ Android ✅ iOS