holographic-sticker
Version:
A React component library for creating holographic sticker effects
341 lines (279 loc) • 10.4 kB
Markdown
# 🌟 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
```bash
npm install holographic-sticker
# or
yarn add holographic-sticker
# or
pnpm add holographic-sticker
```
## 📖 Quick Start
```tsx
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
```tsx
<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
```tsx
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
```tsx
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
```tsx
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:
```css
.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](https://github.com/LAWTED)
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 🐛 Issues
Found a bug? Please [create an issue](https://github.com/LAWTED/holographic-sticker/issues).