react-3d-card

A production-ready, ultra-smooth 3D parallax tilt card package for React. Create breathtaking, premium card interactions with dynamic glare reflections, floating multi-depth parallax layers, gyroscope device orientation tracking, and snappy hover/touch effects.

GitHub Repository: https://github.com/KevalPatel17/react-3d-card

It includes a powerful interactive CLI tool to instantly scaffold self-contained card components directly into your project!

📽️ CLI Interactive Demo

Try the interactive command-line interface directly in your browser: 👉 Open CLI Web Simulator

⚡ Features

• Double-Sided 3D Tilt: Seamlessly rotate, zoom, and tilt cards using mouse coordinates or mobile touch coordinates.
• Floating Parallax Layers: Use multi-depth nesting to make credit cards, character profiles, or dashboard widgets feel alive.
• Dynamic Glare Reflection: Real-time radial glare gradient tracking cursor positions.
• CLI Scaffolder: Generate clean, tailored, zero-dependency TypeScript or JavaScript cards in seconds via npx.
• Responsive Grids: Built-in modular templates for cards grids.
• Hardware Accelerated: Built with smooth CSS transforms and optimized event handlers for fluid 60fps/120fps animations.

🛠️ CLI Scaffolding (Zero-Dependency Components)

If you don't want to load the entire package as a runtime dependency, you can generate customized, standalone, self-contained components directly in your source folder!

Simply run:

npx react-3d-card

Prompt Options:

1. Language target: Choose between TypeScript (.tsx) or JavaScript (.jsx).
2. 3D Shape geometry: Choose preset geometry clip-paths:
   • ■ Square (with custom border-radius)
   • ● Circle
   • ⬡ Hexagon
   • ◆ Diamond
   • ▲ Triangle
   • ★ Star
3. Card Dimension: Select preset sizes (Small, Medium, Large) or set custom dimensions.
4. Layout structure: Choose whether to scaffold a Single Card or a multi-card Grid Layout.
5. Output path: Choose your destination directory (default is ./src/components/Card3D).

The CLI creates clean React files, custom CSS declarations, and a index barrel export in seconds!

📦 Library Installation

To install the core library package inside your React application:

npm install react-3d-card

🚀 Quick Start (Library Component API)

Here is how to render a basic interactive 3D card:

import React from 'react';
import { Card3D, CardFront } from 'react-3d-card';
import 'react-3d-card/dist/index.css'; // Make sure to import styling

export default function App() {
  return (
    <Card3D maxTilt={25} scale={1.08} style={{ width: 320, height: 200 }}>
      <CardFront style={{ background: 'linear-gradient(135deg, #1e1b4b, #311042)', borderRadius: 16 }}>
        <div style={{ padding: 24, color: '#fff' }}>
          <h2>Premium Card</h2>
          <p>Hover me to see 3D tilt effects</p>
        </div>
      </CardFront>
    </Card3D>
  );
}

🪐 Advanced Parallax Layers

Add rich volumetric depth by layering elements at different relative depth levels:

import React from 'react';
import { Card3D, CardFront, CardLayer } from 'react-3d-card';

export function ParallaxCard() {
  return (
    <Card3D maxTilt={30} style={{ width: 300, height: 400 }}>
      <CardFront style={{ background: '#0a0a16', borderRadius: 20, overflow: 'hidden' }}>
        
        {/* Layer 1: Background space image (depth = 0, moves the least) */}
        <CardLayer depth={0}>
          <img src="/stars-bg.jpg" alt="Space" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />
        </CardLayer>

        {/* Layer 2: Floating neon card glow (depth = 12) */}
        <CardLayer depth={12} style={{ display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
          <div style={{ width: 140, height: 140, background: '#a78bfa', filter: 'blur(30px)', opacity: 0.4 }} />
        </CardLayer>

        {/* Layer 3: Main card title and graphic (depth = 25, moves the most) */}
        <CardLayer depth={25} style={{ padding: 30, display: 'flex', flexDirection: 'column', justifyContent: 'space-between', height: '100%' }}>
          <span style={{ color: '#a78bfa', fontSize: 12, fontWeight: 'bold' }}>VIP EXCLUSIVE</span>
          <h1 style={{ color: '#fff', fontSize: 28, margin: '10px 0' }}>OBSIDIAN</h1>
          <p style={{ color: 'rgba(255,255,255,0.6)', fontSize: 13 }}>Level 4 Access Secured</p>
        </CardLayer>

      </CardFront>
    </Card3D>
  );
}

🔄 Double-Sided Cards (Click to Flip)

Combine tilt and flipping by combining <CardFront> and <CardBack> components:

import React, { useState } from 'react';
import { Card3D, CardFront, CardBack } from 'react-3d-card';

export function FlippableCard() {
  const [flipped, setFlipped] = useState(false);

  return (
    <Card3D 
      maxTilt={20} 
      tiltOnClick={true}
      style={{ width: 320, height: 200 }}
    >
      <div 
        onClick={() => setFlipped(!flipped)} 
        style={{ 
          width: '100%', 
          height: '100%', 
          position: 'relative',
          transformStyle: 'preserve-3d',
          transition: 'transform 0.6s cubic-bezier(0.4, 0, 0.2, 1)',
          transform: flipped ? 'rotateY(180deg)' : 'none'
        }}
      >
        {/* Front Face */}
        <CardFront style={{ background: '#1e293b', borderRadius: 16 }}>
          <div style={{ padding: 20, color: '#f8fafc' }}>
            <h3>Credit Card (Front)</h3>
            <p>Click to Flip</p>
          </div>
        </CardFront>

        {/* Back Face */}
        <CardBack style={{ background: '#0f172a', borderRadius: 16, transform: 'rotateY(180deg)' }}>
          <div style={{ padding: 20, color: '#94a3b8' }}>
            <h3>Secure Backend (Back)</h3>
            <p>CVV: •••</p>
          </div>
        </CardBack>
      </div>
    </Card3D>
  );
}

📖 API Reference

<Card3D /> Props

| Prop | Type | Default | Description | |---|---|---|---| | children | React.ReactNode | Required | Child elements, typically wrapping <CardFront> and <CardBack> components. | | maxTilt | number | 20 | Maximum tilt angle in degrees. | | perspective | number | 800 | Perspective depth factor. Smaller values produce more dramatic 3D angles. | | scale | number | 1.05 | Card zoom scale factor applied during hover or touch gestures. | | glare | boolean | true | When active, applies a glossy reflection overlay following mouse/touch coordinates. | | glareMaxOpacity | number | 0.3 | Maximum opacity of the reflective glare overlay. | | shadow | boolean | true | Generates a hardware-accelerated dynamic lift shadow. | | lockAxisX | boolean | false | Disables vertical rotations (locks the card on the X axis). | | lockAxisY | boolean | false | Disables horizontal rotations (locks the card on the Y axis). | | resetTiltOnOutOfBounds | boolean | true | Instantly resets card rotations and scale when mouse leaves the bounds. | | resetTiltOnHover | boolean | false | Resets card rotations back to flat when hovering. | | trackGlobal | boolean \| string | false | Tracks mouse coordinates globally (true or selectors like '.preview-zone') instead of strictly inside the card. | | actionOffset | number | 0 | Adds an active padding offset boundary around the card coordinates trigger. | | transition | string | 'ease-out' | Timing transition function used when resetting the tilt status. | | enableGyro | boolean | false | Enables physical gyroscope tilts (mobile only). | | disabled | boolean | false | Disables tilt interactions completely and renders a flat container. | | tiltOnClick | boolean | false | Gates tilt gestures so rotation only triggers when clicking/dragging. | | onTiltStart | () => void | undefined | Callback fired when the card starts tilting. | | onTiltEnd | () => void | undefined | Callback fired when the card returns to flat. | | onTiltChange | (values: { x: number, y: number }) => void | undefined | Callback fired on every tilt coordinate transition. | | style | React.CSSProperties | undefined | Inline styles for the outer card wrapper container. | | className | string | '' | Custom class name for styling the wrapper. |

<CardLayer /> Props

| Prop | Type | Default | Description | |---|---|---|---| | children | React.ReactNode | Required | Graphic layers elements (text, graphics, labels). | | depth | number | 0 | Parallax offset multiplier. Positive numbers float outward, negative numbers push inward. | | style | React.CSSProperties | undefined | Inline styles for the layer absolute container. | | className | string | '' | Custom class name. |

<CardFront /> & <CardBack /> Props

These components act as standard face containers that support double-sided flipping.

• They accept standard React container properties: children, style, className, and common event handlers.

🎨 CSS Styling Variables

During hover interactions, <Card3D /> publishes active css custom properties dynamically onto the DOM element node. You can consume these variables inside custom CSS files to build custom parallax translations:

• --tilt-x: Active horizontal tilt value in degrees.
• --tilt-y: Active vertical tilt value in degrees.

Example Custom CSS:

.my-card-element {
  transform: translateZ(50px);
  /* Translate based on parent card tilt variables */
  text-shadow: calc(var(--tilt-x) * -0.5px) calc(var(--tilt-y) * 0.5px) 5px rgba(0,0,0,0.3);
}

💻 Compatibility

| Environment | Supported Features | |---|---| | Desktop Browsers | Chrome, Safari, Firefox, Edge (Full support for mouse interactions, glare, and shadow) | | Mobile Web | iOS Safari & Android Chrome (Full support for touch dragging and gyroscope/orientation tracking) | | Next.js / SSR | Safe for SSR. Renders static cards server-side and enables interaction hooks on mount. |

📄 License

MIT License.