React Apple TV Card

A React implementation of the elegant Apple TV card effect with 3D rotation and parallax movement. This component is designed to work seamlessly with React and Next.js applications.

Features

• ✨ Smooth 3D rotation effect on hover
• 🖼️ Beautiful parallax movement with depth layers
• 🎛️ Customizable intensity and rotation limits
• 🌟 Reflection and shadow effects
• 🚀 Built with Framer Motion for performant animations
• 📱 Responsive and mobile-friendly
• 🧩 Full TypeScript support
• ♿ Accessibility features with reduced motion support
• ⚡ Next.js ready (works with both Pages and App Router)

Installation

npm install react-apple-tv-card
# or
yarn add react-apple-tv-card
# or
pnpm add react-apple-tv-card

Requirements

This package requires:

• React 16.8.0 or newer (for Hooks support)
• Framer Motion 6.0.0 or newer

Basic Usage

import AppleTVCard from 'react-apple-tv-card';

function MyComponent() {
  return (
    <AppleTVCard
      title="My Awesome Card"
      backgroundImage="/path/to/image.jpg"
      width={300}
      height={170}
    >
      {/* Optional content with parallax effect */}
      <div style={{ 
        width: '5em', 
        height: '5em', 
        border: '1em dashed white' 
      }} />
    </AppleTVCard>
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | undefined | Title displayed below the card | | backgroundImage | string | undefined | URL for the background image | | width | number | 300 | Width of the card in pixels | | height | number | auto (16:9) | Height of the card in pixels | | autoSize | boolean | false | Whether to size the card relative to its container | | withShadow | boolean | true | Whether to show dynamic shadow effects | | withReflection | boolean | true | Whether to show reflection effects | | rounded | boolean | true | Whether to use rounded corners | | alwaysShowTitle | boolean | false | Whether to always show the title | | shouldShowTitle | boolean | true | Whether to show the title at all | | maxRotation | number | 10 | Maximum rotation angle in degrees | | maxTranslation | number | 10 | Maximum translation distance in pixels | | intensity | number | 1 | Overall intensity of the 3D effect (0-1) | | showBadge | boolean | false | Whether to show a badge in the top-right corner | | badgeCount | number | 0 | The count to display inside the badge | | children | ReactNode | undefined | Content to display with parallax effect | | className | string | '' | Optional CSS class name for the card container | | style | React.CSSProperties | {} | Optional style object for the card container | | onClick | () => void | undefined | Optional callback when the card is clicked |

Advanced Examples

Card with Custom Content and Effects

<AppleTVCard
  title="Movie Title"
  backgroundImage="/movie-poster.jpg"
  width={350}
  height={200}
  maxRotation={15}
  intensity={0.8}
  withShadow={true}
  withReflection={true}
>
  <div style={{
    padding: '1rem',
    background: 'rgba(0,0,0,0.6)',
    color: 'white',
    borderRadius: '0.5rem',
    textAlign: 'center'
  }}>
    <h3>Now Playing</h3>
    <p>Click to watch</p>
  </div>
</AppleTVCard>

Interactive Card with Click Handler

<AppleTVCard
  title="Click Me"
  backgroundImage="/background.jpg"
  onClick={() => alert('Card clicked!')}
  maxRotation={12}
  maxTranslation={8}
>
  <button 
    style={{
      padding: '0.5rem 1rem',
      border: 'none',
      borderRadius: '4px',
      background: 'white',
      cursor: 'pointer'
    }}
  >
    Play Now
  </button>
</AppleTVCard>

Subtle Effect for Professional Use

<AppleTVCard
  title="Product Card"
  backgroundImage="/product.jpg"
  intensity={0.4}
  maxRotation={5}
  maxTranslation={3}
  withReflection={false}
>
  <div className="product-overlay">
    <h4>Premium Product</h4>
    <span className="price">$99.99</span>
  </div>
</AppleTVCard>

Grid of Cards with Auto-sizing

<div style={{ 
  display: 'grid', 
  gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',
  gap: '2rem' 
}}>
  {movies.map(movie => (
    <AppleTVCard
      key={movie.id}
      title={movie.title}
      autoSize={true}
      backgroundImage={movie.posterUrl}
      onClick={() => playMovie(movie.id)}
    />
  ))}
</div>

Accessibility-Friendly Implementation

<AppleTVCard
  title="Accessible Card"
  backgroundImage="/image.jpg"
  onClick={() => navigate('/details')}
  // The component automatically respects prefers-reduced-motion
  // and provides keyboard navigation support
>
  <div role="button" aria-label="View details">
    <span>Learn More</span>
  </div>
</AppleTVCard>

Card with Badge

<AppleTVCard
  title="Notifications"
  backgroundImage="/notification-bg.jpg"
  width={320}
  showBadge={true}
  badgeCount={5}
>
  <div style={{ color: 'white', fontWeight: 'bold' }}>Inbox</div>
</AppleTVCard>

TypeScript Usage

This package includes comprehensive TypeScript definitions:

import AppleTVCard, { AppleTVCardProps } from 'react-apple-tv-card';

// Type-safe wrapper component
const MovieCard: React.FC<{
  movie: Movie;
  onPlay: (id: string) => void;
}> = ({ movie, onPlay }) => {
  return (
    <AppleTVCard
      title={movie.title}
      backgroundImage={movie.posterUrl}
      width={300}
      height={169}
      onClick={() => onPlay(movie.id)}
      maxRotation={12}
      intensity={0.9}
    >
      <div className="movie-overlay">
        <span className="duration">{movie.duration}</span>
        <span className="rating">{movie.rating}</span>
      </div>
    </AppleTVCard>
  );
};

Next.js Usage

App Router (Client Component)

'use client';

import AppleTVCard from 'react-apple-tv-card';

export default function MyPage() {
  return (
    <div>
      <h1>My Gallery</h1>
      <AppleTVCard 
        title="Next.js Card" 
        backgroundImage="/my-image.jpg" 
      />
    </div>
  );
}

With Next.js Image Optimization

'use client';

import AppleTVCard from 'react-apple-tv-card';
import Image from 'next/image';

export default function OptimizedCard() {
  return (
    <AppleTVCard
      title="Optimized Image"
      width={400}
      height={225}
    >
      <Image
        src="/hero-image.jpg"
        alt="Hero"
        fill
        style={{ objectFit: 'cover' }}
        priority
      />
    </AppleTVCard>
  );
}

Performance Tips

• Image Optimization: Use appropriately sized images and consider WebP format for better performance
• Reduced Motion: The component automatically respects prefers-reduced-motion settings
• Intensity Control: Use lower intensity values for better performance on mobile devices
• Virtualization: For large grids, consider implementing virtualization
• Memory Management: The component automatically cleans up event listeners and motion values

Accessibility Features

• ✅ Keyboard navigation support (Tab, Enter, Space)
• ✅ Respects prefers-reduced-motion preference
• ✅ Focus management with visual indicators
• ✅ Screen reader compatible
• ✅ Touch device optimization

Browser Support

• Chrome 88+
• Firefox 87+
• Safari 14+
• Edge 88+

Troubleshooting

Common Issues

Card not rotating properly: Ensure the parent container has enough space and doesn't have overflow: hidden set.

Performance issues: Try reducing the intensity prop or disabling withReflection on mobile devices.

TypeScript errors: Make sure you have the latest version of @types/react installed.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See our Contributing Guide for details.

Changelog

See CHANGELOG.md for a detailed list of changes.

License

MIT © BlakCode

Inspired by the elegant card interactions in Apple's tvOS interface.