3D Card Flip with Touch & Mouse Drag – TouchFlip3D-Web

TouchFlip3D-Web is a vanilla JavaScript Web Component that flips HTML elements in 3D space in response to drag and touch gestures.

It requires no external dependencies and uses the Shadow DOM to keep its internal styles completely isolated from the host page.

Features:

• Touch gesture support: Responds to native touch events for smooth 3D rotation on mobile and tablet.
• Mouse drag support: Fully interactive on desktop — drag in any direction to rotate the card freely.
• Shadow DOM encapsulation: All internal CSS lives inside the Shadow DOM. It does not bleed into your stylesheet, and your global styles do not interfere with the component.
• Anti-selection UX: Text selection is blocked on both the front and back faces during a drag interaction. This prevents the accidental highlight behavior that commonly breaks 3D drag UX.
• Slotted content model: Both card faces accept arbitrary HTML through named slots (front and back). You control the markup and styling of each face completely.
• Free-axis rotation: The card rotates on both X and Y axes simultaneously, tracking the user’s drag direction precisely — not just a horizontal flip.
• Passive event optimization: Touch move events are registered with {passive: false} only where cancellation is required, so scroll performance on the rest of the page is preserved.

Use Cases:

• Product Cards: E-commerce sites can display product images on the front with specifications on the back through drag interaction.
• Interactive Portfolios: Designers and photographers can present work samples that flip to reveal project details.
• Flashcard Applications: Educational tools benefit from the natural flip motion for study aids and quizzes.
• Mobile Menus: Navigation elements can rotate to show secondary options while conserving screen space.

How To Use It:

1. Install touch-flip-3d-web and import it into your main JS file:

# NPM
$ npm install touch-flip-3d-web

import 'touch-flip-3d-web';

2. Or directly import the ‘TouchFlip3D.js’ file into your HTML document.

<script src="TouchFlip3D.js"></script>

3. After the script loads, the <touch-flip-3d> custom element is globally available. Place your front and back content inside it using the named slot attributes:

<!--
  Set explicit width and height on the component.
  The inner faces will stretch to fill this container.
-->
<touch-flip-3d style="width: 320px; height: 200px;">
  <!-- The front face — shown by default -->
  <div slot="front" style="background: #0f3460; color: #eaeaea; border-radius: 12px; padding: 24px;">
    <h3>Developer Profile</h3>
    <p>Drag or swipe to flip</p>
  </div>
  <!-- The back face — rotated 180deg on the Y axis initially -->
  <div slot="back" style="background: #16213e; color: #eaeaea; border-radius: 12px; padding: 24px;">
    <h3>Contact Info</h3>
    <p>[email protected]</p>
  </div>
</touch-flip-3d>

4. You can place multiple <touch-flip-3d> elements on the same page. Each instance manages its own drag state internally.

<div style="display: flex; gap: 24px; flex-wrap: wrap;">
  <!-- Card 1: Pricing tier -->
  <touch-flip-3d style="width: 280px; height: 180px;">
    <div slot="front" style="background: #1b4332; color: white; border-radius: 10px; padding: 20px;">
      <h4>Starter Plan</h4>
      <p>$9 / month</p>
    </div>
    <div slot="back" style="background: #2d6a4f; color: white; border-radius: 10px; padding: 20px;">
      <ul>
        <li>10 projects</li>
        <li>5 GB storage</li>
        <li>Email support</li>
      </ul>
    </div>
  </touch-flip-3d>
  <!-- Card 2: Another tier -->
  <touch-flip-3d style="width: 280px; height: 180px;">
    <div slot="front" style="background: #7b2d8b; color: white; border-radius: 10px; padding: 20px;">
      <h4>Pro Plan</h4>
      <p>$29 / month</p>
    </div>
    <div slot="back" style="background: #5e2270; color: white; border-radius: 10px; padding: 20px;">
      <ul>
        <li>Unlimited projects</li>
        <li>50 GB storage</li>
        <li>Priority support</li>
      </ul>
    </div>
  </touch-flip-3d>
</div>

5. The component uses perspective: 1200px on the host element. To get a deeper or shallower 3D effect, wrap the <touch-flip-3d> in a container and apply your own perspective to that wrapper:

/* Adjust the depth of the 3D perspective from outside the component */
.card-wrapper {
  perspective: 800px; /* lower value = more dramatic depth */
}

Each slotted face fills 100% of the component’s width and height. Set the dimensions on the <touch-flip-3d> element, not on the child divs:

touch-flip-3d {
  width: 360px;
  height: 220px;
  display: block; /* the component sets this in Shadow DOM, but explicit is safe */
}