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

1npm install react-apple-tv-card
2# or
3yarn add react-apple-tv-card
4# or
5pnpm 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

1import AppleTVCard from 'react-apple-tv-card';
2
3function MyComponent() {
4  return (
5    <AppleTVCard
6      title="My Awesome Card"
7      backgroundImage="/path/to/image.jpg"
8      width={300}
9      height={170}
10    >
11      {/* Optional content with parallax effect */}
12      <div style={{ 
13        width: '5em', 
14        height: '5em', 
15        border: '1em dashed white' 
16      }} />
17    </AppleTVCard>
18  );
19}

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

1<AppleTVCard
2  title="Movie Title"
3  backgroundImage="/movie-poster.jpg"
4  width={350}
5  height={200}
6  maxRotation={15}
7  intensity={0.8}
8  withShadow={true}
9  withReflection={true}
10>
11  <div style={{
12    padding: '1rem',
13    background: 'rgba(0,0,0,0.6)',
14    color: 'white',
15    borderRadius: '0.5rem',
16    textAlign: 'center'
17  }}>
18    <h3>Now Playing</h3>
19    <p>Click to watch</p>
20  </div>
21</AppleTVCard>

Interactive Card with Click Handler

1<AppleTVCard
2  title="Click Me"
3  backgroundImage="/background.jpg"
4  onClick={() => alert('Card clicked!')}
5  maxRotation={12}
6  maxTranslation={8}
7>
8  <button 
9    style={{
10      padding: '0.5rem 1rem',
11      border: 'none',
12      borderRadius: '4px',
13      background: 'white',
14      cursor: 'pointer'
15    }}
16  >
17    Play Now
18  </button>
19</AppleTVCard>

Subtle Effect for Professional Use

1<AppleTVCard
2  title="Product Card"
3  backgroundImage="/product.jpg"
4  intensity={0.4}
5  maxRotation={5}
6  maxTranslation={3}
7  withReflection={false}
8>
9  <div className="product-overlay">
10    <h4>Premium Product</h4>
11    <span className="price">$99.99</span>
12  </div>
13</AppleTVCard>

Grid of Cards with Auto-sizing

1<div style={{ 
2  display: 'grid', 
3  gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',
4  gap: '2rem' 
5}}>
6  {movies.map(movie => (
7    <AppleTVCard
8      key={movie.id}
9      title={movie.title}
10      autoSize={true}
11      backgroundImage={movie.posterUrl}
12      onClick={() => playMovie(movie.id)}
13    />
14  ))}
15</div>

Accessibility-Friendly Implementation

1<AppleTVCard
2  title="Accessible Card"
3  backgroundImage="/image.jpg"
4  onClick={() => navigate('/details')}
5  // The component automatically respects prefers-reduced-motion
6  // and provides keyboard navigation support
7>
8  <div role="button" aria-label="View details">
9    <span>Learn More</span>
10  </div>
11</AppleTVCard>

Card with Badge

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

TypeScript Usage

This package includes comprehensive TypeScript definitions:

1import AppleTVCard, { AppleTVCardProps } from 'react-apple-tv-card';
2
3// Type-safe wrapper component
4const MovieCard: React.FC<{
5  movie: Movie;
6  onPlay: (id: string) => void;
7}> = ({ movie, onPlay }) => {
8  return (
9    <AppleTVCard
10      title={movie.title}
11      backgroundImage={movie.posterUrl}
12      width={300}
13      height={169}
14      onClick={() => onPlay(movie.id)}
15      maxRotation={12}
16      intensity={0.9}
17    >
18      <div className="movie-overlay">
19        <span className="duration">{movie.duration}</span>
20        <span className="rating">{movie.rating}</span>
21      </div>
22    </AppleTVCard>
23  );
24};

Next.js Usage

App Router (Client Component)

1'use client';
2
3import AppleTVCard from 'react-apple-tv-card';
4
5export default function MyPage() {
6  return (
7    <div>
8      <h1>My Gallery</h1>
9      <AppleTVCard 
10        title="Next.js Card" 
11        backgroundImage="/my-image.jpg" 
12      />
13    </div>
14  );
15}

With Next.js Image Optimization

1'use client';
2
3import AppleTVCard from 'react-apple-tv-card';
4import Image from 'next/image';
5
6export default function OptimizedCard() {
7  return (
8    <AppleTVCard
9      title="Optimized Image"
10      width={400}
11      height={225}
12    >
13      <Image
14        src="/hero-image.jpg"
15        alt="Hero"
16        fill
17        style={{ objectFit: 'cover' }}
18        priority
19      />
20    </AppleTVCard>
21  );
22}

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.