HoloTilt

A high-performance 3D parallax tilt card library for Flutter with dynamic multi-layer lighting, realistic perspective distortion, iridescent holographic foil shimmer presets, floating Z-depth parallax layers, and physics-based spring recoil.

🎬 Preview

HoloTilt Parallax Card Demo

✨ Features

🎮 Smooth 3D Perspective Tilt: Realistic Matrix4 3D rotation responding to drag gestures on mobile and mouse hover on desktop/web.
🌈 Dynamic Multi-Layer Lighting:
- Dynamic Cast Shadow: Shifts inversely with card tilt angle for deep realistic physical depth.
- Specular Highlight Sweep: Gleaming light reflections that glide across card surfaces.
- Holographic Foil Shimmer: Iridescent sheen composited with canvas BlendMode.overlay.
- Radial Flare: Angle-sensitive specular reflection flare.
🎨 Built-in Foil Presets (HoloPreset):
- gold — Royal gold and sparkle champagne shine.
- rainbow — Full-spectrum iridescent holographic foil.
- silver — Platinum, icy chrome, and diamond sheen.
- neonCyber — Electric cyan, magenta, and purple cyberpunk shimmer.
- emerald — Emerald, mint, and teal gemstone glitter.
- cosmic — Deep indigo, violet, and rose starlight.
🌌 Multi-Layer 3D Parallax (HoloParallaxLayer): Float badges, icons, images, or text at configurable Z-depth planes above or below the card.
🪀 Physics-Based Recoil: Spring-like easing (Curves.elasticOut) snaps the card back to center smoothly when released.
📱 True Cross-Platform: Ready for iOS, Android, Web, macOS, Windows, and Linux out-of-the-box.
⚡ Zero External Heavy Dependencies: Pure Flutter rendering for 60fps / 120fps performance and minimal app binary footprint.

🚀 Getting Started

Add holotilt to your pubspec.yaml:

dependencies:
  holotilt: ^1.0.0

Or run:

flutter pub add holotilt

Import the package in your Dart code:

import 'package:holotilt/holotilt.dart';

💡 Quick Start

Wrap any child widget with HoloTilt:

import 'package:flutter/material.dart';
import 'package:holotilt/holotilt.dart';

class MyTiltCard extends StatelessWidget {
  const MyTiltCard({super.key});

  @override
  Widget build(BuildContext context) {
    return Center(
      child: HoloTilt(
        width: 300,
        height: 420,
        preset: HoloPreset.gold,
        borderRadius: BorderRadius.circular(20),
        child: Container(
          decoration: BoxDecoration(
            borderRadius: BorderRadius.circular(20),
            gradient: const LinearGradient(
              colors: [Color(0xFFBF953F), Color(0xFFFCF6BA), Color(0xFFB38728)],
              begin: Alignment.topLeft,
              end: Alignment.bottomRight,
            ),
          ),
          child: const Center(
            child: Text(
              "HOLOGRAPHIC CARD",
              style: TextStyle(
                color: Colors.white,
                fontSize: 20,
                fontWeight: FontWeight.bold,
              ),
            ),
          ),
        ),
      ),
    );
  }
}

🌌 Creating Floating 3D Parallax Layers

Use HoloParallaxLayer to give individual elements inside your card a floating 3D pop-out effect:

HoloTilt(
  width: 300,
  height: 440,
  preset: HoloPreset.rainbow,
  child: Stack(
    children: [
      // Background base layer (depth = 0)
      Container(color: const Color(0xFF1E1E24)),

      // Floating artwork (depth = 35)
      Center(
        child: HoloParallaxLayer(
          depth: 35.0,
          child: Image.asset('assets/character.png'),
        ),
      ),

      // Floating header badge (depth = 55)
      Positioned(
        top: 20,
        left: 20,
        child: HoloParallaxLayer(
          depth: 55.0,
          child: Container(
            padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 4),
            decoration: BoxDecoration(
              color: Colors.black54,
              borderRadius: BorderRadius.circular(8),
            ),
            child: const Text(
              "ULTRA RARE",
              style: TextStyle(color: Colors.white, fontWeight: FontWeight.bold),
            ),
          ),
        ),
      ),
    ],
  ),
)

⚙️ Properties & Customization

Property	Type	Default	Description
`child`	`Widget`	required	The content displayed inside the card.
`width`	`double?`	`null`	Optional fixed width of the card.
`height`	`double?`	`null`	Optional fixed height of the card.
`borderRadius`	`BorderRadiusGeometry`	`BorderRadius.circular(20)`	Corner radius for the card and overlays.
`preset`	`HoloPreset`	`HoloPreset.gold`	Color preset for holographic foil shimmer.
`maxTiltDegrees`	`double`	`12.0`	Maximum tilt angle in degrees.
`sensitivity`	`double`	`0.002`	Drag gesture sensitivity factor.
`perspective`	`double`	`0.001`	3D perspective distortion factor.
`recenterDuration`	`Duration`	`600ms`	Duration for spring recoil animation.
`recenterCurve`	`Curve`	`Curves.elasticOut`	Spring recoil animation curve.
`enableHover`	`bool`	`true`	Enables tilt on mouse hover (Desktop/Web).
`enableTouchGesture`	`bool`	`true`	Enables tilt on pan/touch drag (Mobile).
`enableShadow`	`bool`	`true`	Enables dynamic angle-responsive shadow.
`shadowColor`	`Color?`	`null`	Custom shadow color (defaults to preset).
`enableShimmer`	`bool`	`true`	Enables holographic foil shimmer overlay.
`customShimmerGradient`	`Gradient?`	`null`	Custom gradient to override presets.
`shimmerBlendMode`	`BlendMode`	`BlendMode.overlay`	Blend mode for foil shimmer layer.
`enableSpecularHighlight`	`bool`	`true`	Enables moving specular highlight sweep.
`enableRadialFlare`	`bool`	`true`	Enables radial flare reflection.
`onTiltUpdate`	`ValueChanged<Offset>?`	`null`	Callback giving current tilt radians `(rotY, rotX)`.
`onTiltEnd`	`VoidCallback?`	`null`	Callback fired when user finishes tilting.
`controller`	`HoloTiltController?`	`null`	Programmatic tilt controller.

🕹 Programmatic Control

You can tilt or reset the card programmatically using HoloTiltController:

final controller = HoloTiltController();

// Tilt card programmatically (rotY, rotX in radians)
controller.setTilt(0.15, -0.1);

// Recenter back to flat
controller.reset();

// Connect to widget:
HoloTilt(
  controller: controller,
  child: myContent,
);