GifPlayer

GifPlayer component: animated GIF with play/pause toggle, reduced motion support, and accessible alt text for tour steps

Overview

GifPlayer provides user-controlled playback for animated GIFs with accessibility features and reduced motion support. Perfect for feature demos, quick tutorials, and lightweight animations without video overhead.

Why Use GifPlayer?

User control: Play/pause prevents distracting auto-play
Lightweight: No video codec overhead, smaller file sizes
Accessibility: Respects prefers-reduced-motion, keyboard controls
Simple creation: Easier to create than videos
Universal support: Works everywhere, no codec issues

Basic Usage

import { GifPlayer } from '@tour-kit/media'

export function FeatureDemo() {
  return (
    <GifPlayer
      src="/animations/feature-demo.gif"
      alt="Feature demonstration animation"
      poster="/images/feature-poster.jpg"
    />
  )
}

Props

Prop

Type

Examples

Basic GIF with Controls

<GifPlayer
  src="/animations/dashboard-tour.gif"
  alt="Dashboard navigation tutorial"
  poster="/images/dashboard-poster.jpg"
/>

Auto-playing GIF

Start playing automatically on load:

<GifPlayer
  src="/animations/quick-demo.gif"
  alt="Quick feature demonstration"
  autoplay
/>

Use autoplay sparingly. Auto-playing animations can be distracting and inaccessible for users with motion sensitivity.

Custom Control Position

Place controls in the corner for less obstruction:

<GifPlayer
  src="/animations/feature.gif"
  alt="Feature walkthrough"
  controlPosition="bottom-right"
/>

Hidden Controls

Auto-play without user controls:

<GifPlayer
  src="/animations/background.gif"
  alt="Background animation"
  autoplay
  showControls={false}
/>

Square GIF for Mobile

<GifPlayer
  src="/animations/mobile-demo.gif"
  alt="Mobile app demonstration"
  aspectRatio="1/1"
  size="sm"
  rounded="lg"
/>

Reduced Motion Fallback

Show static image for motion-sensitive users:

<GifPlayer
  src="/animations/animated-feature.gif"
  alt="Animated feature showcase"
  poster="/images/feature-static.jpg"
  reducedMotionFallback="/images/feature-static.jpg"
/>

Event Tracking

Track when users play animations:

<GifPlayer
  src="/animations/tutorial.gif"
  alt="Tutorial animation"
  onPlay={() => {
    analytics.track('GIF Played', { animation: 'tutorial' })
  }}
  onPause={() => {
    analytics.track('GIF Paused', { animation: 'tutorial' })
  }}
/>

Creating Effective GIFs

File Size Optimization

GIFs can be large. Optimize before using:

Tools:

Gifski - High-quality GIF encoder
ezgif.com - Online GIF optimizer
Gifsicle - Command-line optimizer

Best practices:

Keep duration under 10 seconds
Reduce frame rate (10-15 FPS is often sufficient)
Limit dimensions (max 800px wide)
Reduce colors (256 or fewer)
Compress with tools like Gifski

Recording Screen GIFs

Tools for screen recordings:

LICEcap - Windows/Mac
Kap - Mac only
ScreenToGif - Windows

Recording tips:

Use consistent mouse movements
Pause briefly before and after actions
Keep recording area small
Record at 2x speed, play at 1x

When to Use GIF vs Video

Choose GIF when:

Animation is short (< 10 seconds)
File size < 2MB after optimization
Universal compatibility required
Simple animations without audio

Choose Video when:

Duration > 10 seconds
Audio is needed
File size > 2MB
Need better quality at smaller sizes

Accessibility

Required Alt Text

Describe what the animation shows:

// Good - describes the action
<GifPlayer
  src="signup-flow.gif"
  alt="Step-by-step animation of the sign-up process"
/>

// Bad - too vague
<GifPlayer
  src="signup-flow.gif"
  alt="GIF animation"
/>

Reduced Motion Support

Always provide a fallback for users who prefer reduced motion:

<GifPlayer
  src="animated-demo.gif"
  alt="Feature demo"
  reducedMotionFallback="static-demo.jpg"
/>

This respects the prefers-reduced-motion: reduce CSS media query.

User Control

Never auto-play without user control:

// Good - user can control playback
<GifPlayer
  src="demo.gif"
  alt="Demo"
  showControls
/>

// Bad - auto-plays without control
<GifPlayer
  src="demo.gif"
  alt="Demo"
  autoplay
  showControls={false}
/>

Keyboard Accessibility

The play/pause button is keyboard accessible:

Tab - Focus the play/pause button
Enter or Space - Toggle playback
Escape - Pause (if playing)

Use Cases

Feature Announcements

Show new features with quick GIFs:

<Announcement id="new-search">
  <h2>Introducing: Advanced Search</h2>
  <GifPlayer
    src="/animations/advanced-search.gif"
    alt="Advanced search feature demonstration"
    autoplay
  />
  <p>Find what you need faster with filters and operators.</p>
</Announcement>

Inline Help

Embed small tutorial GIFs in documentation:

<div className="help-section">
  <h3>How to Export Data</h3>
  <GifPlayer
    src="/help/export-data.gif"
    alt="Steps to export data from the dashboard"
    size="sm"
    controlPosition="bottom-right"
  />
  <p>Click the export button and select your format.</p>
</div>

Tour Steps

Use in onboarding flows:

import { Tour, TourStep } from '@tour-kit/react'
import { GifPlayer } from '@tour-kit/media'

<Tour id="feature-tour">
  <TourStep id="navigation">
    <h2>Navigating the Dashboard</h2>
    <GifPlayer
      src="/tours/navigation.gif"
      alt="Dashboard navigation demonstration"
      autoplay
    />
  </TourStep>
</Tour>

Loading States

Show what's happening during long operations:

<div className="processing">
  <GifPlayer
    src="/animations/processing.gif"
    alt="Data processing animation"
    autoplay
    showControls={false}
    size="sm"
  />
  <p>Processing your data...</p>
</div>

Performance Considerations

Lazy Loading

Load GIFs only when visible:

import { useInView } from 'react-intersection-observer'

function LazyGif() {
  const { ref, inView } = useInView({ triggerOnce: true })

  return (
    <div ref={ref}>
      {inView && (
        <GifPlayer
          src="/large-animation.gif"
          alt="Feature demo"
        />
      )}
    </div>
  )
}

Poster Images

Always provide poster images to reduce initial load:

<GifPlayer
  src="large-demo.gif"
  alt="Demo"
  poster="demo-poster.jpg" // Loads immediately, GIF loads on demand
/>

TypeScript

Full type safety with autocompletion:

import type { GifPlayerProps } from '@tour-kit/media'

const config: GifPlayerProps = {
  src: '/animations/demo.gif',
  alt: 'Feature demonstration',
  poster: '/images/demo-poster.jpg',
  autoplay: false,
  showControls: true,
  controlPosition: 'bottom-right'
}

<GifPlayer {...config} />