🌟 Holographic Sticker

A React component library for creating stunning holographic sticker effects with 3D transformations and interactive animations.

✨ Features

• 🎯 Easy to Use: Simple compound component API
• 🎨 Customizable: Flexible styling and configuration options
• 📱 Responsive: Works great on mobile and desktop
• ⚡ Performance: Optimized animations and GPU acceleration
• 🔧 TypeScript: Full TypeScript support with type definitions
• 🎭 Accessible: Built with accessibility in mind

🚀 Installation

npm install holographic-sticker
# or
yarn add holographic-sticker
# or
pnpm add holographic-sticker

📖 Quick Start

import HolographicSticker from 'holographic-sticker';

function App() {
  return (
    <div className="flex items-center justify-center min-h-screen bg-black">
      <HolographicSticker.Root>
        <HolographicSticker.Controls />
        <HolographicSticker.Minimap />
        <HolographicSticker.Scene>
          <HolographicSticker.Card className="border border-white rounded-2xl">
            <HolographicSticker.ImageLayer
              src="/lightning.png"
              alt="Lightning"
              objectFit="contain"
            />
            <HolographicSticker.Pattern
              maskUrl="/lightning.png"
              maskSize="contain"
              textureUrl="https://assets.codepen.io/605876/figma-texture.png"
              mixBlendMode="hard-light"
              opacity={0.7}
            >
              <HolographicSticker.Refraction intensity={2} />
            </HolographicSticker.Pattern>
            <HolographicSticker.Content>
              <HolographicSticker.ImageLayer
                src="/lightning.png"
                alt=""
                opacity={0.2}
                objectFit="contain"
              />
            </HolographicSticker.Content>
          </HolographicSticker.Card>
        </HolographicSticker.Scene>
      </HolographicSticker.Root>
    </div>
  );
}

🏗️ Component Architecture

The library follows a structured component hierarchy:

1. Root: Mouse tracking context and global controls
2. Scene: 3D scene container
3. Card: Individual sticker container with layers
4. ImageLayer: Image display with various blend modes
5. Pattern: Holographic effects container
6. Content: Overlay content container

<HolographicSticker.Root>              {/* Mouse tracking context */}
  <HolographicSticker.Controls />      {/* Interactive controls */}
  <HolographicSticker.Minimap />       {/* Navigation minimap */}
  <HolographicSticker.Scene>           {/* 3D scene container */}
    <HolographicSticker.Card>          {/* Individual sticker */}
      <HolographicSticker.ImageLayer /> {/* Base image layer */}
      <HolographicSticker.Pattern>     {/* Holographic effects */}
        <HolographicSticker.Refraction /> {/* Light refraction */}
      </HolographicSticker.Pattern>
      <HolographicSticker.Content>     {/* Overlay content */}
        <HolographicSticker.ImageLayer /> {/* Overlay images */}
      </HolographicSticker.Content>
    </HolographicSticker.Card>
  </HolographicSticker.Scene>
</HolographicSticker.Root>

📚 API Reference

HolographicSticker.Root

The main container that provides mouse tracking context.

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Child components | | className | string | '' | Additional CSS classes |

HolographicSticker.Scene

The 3D scene container that manages the holographic environment.

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Child components (Cards) | | className | string | '' | Additional CSS classes |

HolographicSticker.Card

The individual sticker container that handles 3D transformations.

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Child components | | className | string | '' | Additional CSS classes |

HolographicSticker.ImageLayer

Displays images with various blend modes and effects.

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | - | Image source URL | | alt | string | '' | Image alt text | | className | string | '' | Additional CSS classes | | opacity | number | 1 | Layer opacity (0-1) | | objectFit | string | 'cover' | CSS object-fit property |

HolographicSticker.Pattern

The holographic pattern layer container with mask and texture support.

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Child components (usually Refraction) | | className | string | '' | Additional CSS classes | | maskUrl | string | - | Mask image URL | | maskSize | string | 'contain' | Mask size property | | textureUrl | string | Built-in texture | Custom texture URL | | textureSize | string | - | Texture size | | mixBlendMode | string | - | CSS mix-blend-mode | | opacity | number | 1 | Pattern opacity (0-1) |

HolographicSticker.Refraction

The rainbow refraction effect component.

| Prop | Type | Default | Description | |------|------|---------|-------------| | className | string | '' | Additional CSS classes | | intensity | number | 1 | Refraction intensity |

HolographicSticker.Content

Container for overlay content and additional image layers.

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Child components | | className | string | '' | Additional CSS classes |

HolographicSticker.Controls

Interactive controls for customizing the holographic effects.

| Prop | Type | Default | Description | |------|------|---------|-------------| | className | string | '' | Additional CSS classes |

HolographicSticker.Minimap

Navigation minimap for the holographic scene.

| Prop | Type | Default | Description | |------|------|---------|-------------| | className | string | '' | Additional CSS classes |

🎨 Examples

Basic Usage

import HolographicSticker from 'holographic-sticker';

function BasicExample() {
  return (
    <HolographicSticker.Root>
      <HolographicSticker.Scene>
        <HolographicSticker.Card className="border border-white rounded-2xl">
          <HolographicSticker.ImageLayer 
            src="/image.jpg" 
            alt="Example"
            objectFit="contain"
          />
          <HolographicSticker.Pattern
            maskUrl="/image.jpg"
            maskSize="contain"
          >
            <HolographicSticker.Refraction />
          </HolographicSticker.Pattern>
          <HolographicSticker.Content>
            <HolographicSticker.ImageLayer 
              src="/image.jpg" 
              alt="" 
              opacity={0.2}
              objectFit="contain"
            />
          </HolographicSticker.Content>
        </HolographicSticker.Card>
      </HolographicSticker.Scene>
    </HolographicSticker.Root>
  );
}

With Controls and Minimap

function FullFeaturedExample() {
  return (
    <HolographicSticker.Root>
      <HolographicSticker.Controls />
      <HolographicSticker.Minimap />
      <HolographicSticker.Scene>
        <HolographicSticker.Card className="border-2 border-white/20 rounded-3xl">
          <HolographicSticker.ImageLayer 
            src="/fire.png" 
            alt="Fire"
            objectFit="contain"
            className="brightness-110"
          />
          <HolographicSticker.Pattern 
            maskUrl="/fire.png"
            maskSize="contain"
            textureUrl="https://assets.codepen.io/605876/figma-texture.png"
            mixBlendMode="hard-light"
            opacity={0.6}
          >
            <HolographicSticker.Refraction intensity={2} />
          </HolographicSticker.Pattern>
          <HolographicSticker.Content>
            <HolographicSticker.ImageLayer 
              src="/fire.png"
              alt=""
              opacity={0.3}
              objectFit="contain"
            />
          </HolographicSticker.Content>
        </HolographicSticker.Card>
      </HolographicSticker.Scene>
    </HolographicSticker.Root>
  );
}

Multiple Cards Gallery

function Gallery() {
  const cards = [
    { src: '/fire.png', alt: 'Fire' },
    { src: '/water.png', alt: 'Water' },
    { src: '/earth.png', alt: 'Earth' },
  ];

  return (
    <HolographicSticker.Root>
      <HolographicSticker.Controls />
      <HolographicSticker.Scene>
        <div className="flex gap-8 justify-center">
          {cards.map((card, index) => (
            <HolographicSticker.Card key={index} className="border border-white/20 rounded-2xl">
              <HolographicSticker.ImageLayer {...card} objectFit="contain" />
              <HolographicSticker.Pattern
                maskUrl={card.src}
                maskSize="contain"
              >
                <HolographicSticker.Refraction />
              </HolographicSticker.Pattern>
              <HolographicSticker.Content>
                <HolographicSticker.ImageLayer 
                  src={card.src} 
                  alt="" 
                  opacity={0.2}
                  objectFit="contain"
                />
              </HolographicSticker.Content>
            </HolographicSticker.Card>
          ))}
        </div>
      </HolographicSticker.Scene>
    </HolographicSticker.Root>
  );
}

🎯 CSS Custom Properties

You can customize the appearance using CSS custom properties:

.holographic-sticker-card {
  --holographic-rotate-x: 30deg;  /* X-axis rotation intensity */
  --holographic-rotate-y: -25deg; /* Y-axis rotation intensity */
}

.holographic-sticker-pattern {
  --pattern-intensity: 0.6; /* Pattern opacity */
}

.holographic-sticker-overlay {
  --overlay-opacity: 0.3; /* Overlay opacity */
}

🌍 Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

📄 License

MIT © Lawted Wu

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

Found a bug? Please create an issue.