spatial_card #

✨ Why spatial_card? #

Most card widgets in Flutter are flat 2D boxes with static box shadows. Previous attempts at 3D depth often relied on heavy 30+ MB machine-learning models (like TFLite depth estimation) that suffer from native build failures, slow load times, and high memory usage.

spatial_card takes a pure-Flutter, zero-native-dependency approach:

• ⚡ Ultra Lightweight (< 50 KB): Zero heavy ML model weights or C++ dependencies.
• 🚀 Silky 120 FPS Performance: Fully hardware-accelerated via Impeller and Skia.
• 💎 True Multi-Plane Z-Parallax: Position any Flutter widget on distinct elevation planes (SpatialLayer) with dynamic drop shadows.
• 🌈 Physical Specular & Chromatic Sheen: Dynamic specular glare and prismatic rainbow dispersion that react fluidly to finger touches and cursor hover.
• 🔄 3D Double-Sided Flip: Flip between front and back faces with continuous 3D perspective (SpatialFlipCard).
• 📚 3D Card Stack / Deck: Depth-scaled swipeable card carousels (SpatialCardStack).
• 🌐 100% Cross-Platform: Flawless support for iOS, Android, Web, macOS, Windows, and Linux.

📸 Architecture & Visual Overview #

📦 Installation #

Add spatial_card to your pubspec.yaml:

dependencies:
  spatial_card: ^1.0.2

Or install via terminal:

flutter pub add spatial_card

🚀 Quick Start #

Wrap your widgets in SpatialCard and assign elements to separate elevation planes using SpatialLayer:

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

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: const Color(0xFF0A0F1D),
      body: Center(
        child: SpatialCard(
          material: SpatialMaterial.holographicFoil(),
          config: const SpatialConfig(parallaxIntensity: 28.0),
          layers: [
            // Base layer (Z = 0)
            SpatialLayer.base(
              alignment: Alignment.topLeft,
              child: const Padding(
                padding: EdgeInsets.all(24.0),
                child: Text(
                  'APEX // COLLECTIBLE',
                  style: TextStyle(color: Colors.white70, fontWeight: FontWeight.bold),
                ),
              ),
            ),
            // Floating high-depth layer (Z = 1.0)
            SpatialLayer.floating(
              alignment: Alignment.center,
              child: const Icon(Icons.diamond_outlined, color: Colors.cyanAccent, size: 56),
            ),
            // Mid layer (Z = 0.5)
            SpatialLayer.mid(
              alignment: Alignment.bottomLeft,
              child: const Padding(
                padding: EdgeInsets.all(24.0),
                child: Text(
                  'GOVIND TANK',
                  style: TextStyle(color: Colors.white, fontSize: 16, fontWeight: FontWeight.bold),
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

🎨 Built-In Material Presets #

spatial_card includes six meticulously crafted material presets ready out of the box:

🔄 3D Double-Sided Flip Card #

Easily create flip cards that rotate 180° in 3D space with continuous lighting:

SpatialFlipCard(
  frontMaterial: SpatialMaterial.cyberNeon(),
  backMaterial: SpatialMaterial.cyberNeon(),
  frontLayers: [
    SpatialLayer.floating(
      alignment: Alignment.center,
      child: const Text('TAP TO REVEAL QR', style: TextStyle(color: Colors.white)),
    ),
  ],
  backLayers: [
    SpatialLayer.floating(
      alignment: Alignment.center,
      child: Container(
        color: Colors.white,
        padding: const EdgeInsets.all(8),
        child: const Icon(Icons.qr_code_2, size: 64, color: Colors.black),
      ),
    ),
  ],
)

📚 3D Card Stack / Deck #

Create swipeable layered card stacks with progressive depth scaling and defocus blur:

SpatialCardStack(
  layerOffset: 18.0,
  scaleStep: 0.05,
  children: [
    SpatialCard(material: SpatialMaterial.goldFoil(), ...),
    SpatialCard(material: SpatialMaterial.carbonFiber(), ...),
    SpatialCard(material: SpatialMaterial.holographicFoil(), ...),
  ],
)

🎛️ Physical Dynamics & Customization #

Fine-tune every aspect of the physics and perspective with SpatialConfig:

SpatialConfig(
  maxTiltAngle: 0.35,          // Max tilt in radians (~20 deg)
  perspective: 0.0015,         // Perspective factor (Z distortion)
  parallaxIntensity: 24.0,     // Parallax distance multiplier
  pressDepression: 0.06,       // Z-depth pushback on press
  pressScale: 0.98,            // Tactile scale squish
  springDamping: 0.75,         // Snap-back spring damping
  enableHaptics: true,         // Micro-haptics on interaction
  enableIdleDrift: true,       // Ambient figure-8 light breathing
  idleDriftSpeed: 1.0,         // Speed of ambient drift
)

📱 Running the Example #

Clone the repository and run the demo application:

git clone https://github.com/govindtank/spatial_card.git
cd spatial_card/example
flutter run

🔗 Recommended Ecosystem Pairings #

Elevate your Flutter application by pairing spatial_card with other companion libraries:

• ambient_backdrop_glow — Dynamic background glow and fluid mesh gradients extracted from image artwork with OKLab color blending.
• ai_voice_orb — Fluid audio-reactive neural voice orb for Conversational AI agents.
• dart_vector_index — Pure-Dart vector search & HNSW index for on-device RAG.

🤝 Contributing #

Contributions, issues, and feature requests are welcome! Feel free to open an issue or pull request on GitHub.

💖 Support the Project #

If you find this project useful, consider supporting its active maintenance and future development:

📄 License #

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Maintained with ❤️ by Govind Tank.