Skip to content

UI Library for Design Engineers. Animated components and effects you can copy and paste into your apps. Free. Open Source.

feat: Add Pixel Image Component (#694)

Dharmin Nagar19e6a9af6093
diff --git a/__registry__/index.tsx b/__registry__/index.tsx
index 35dc9e7f..aef12754 100644
--- a/__registry__/index.tsx
+++ b/__registry__/index.tsx
@@ -1578,6 +1578,30 @@ export const Index: Record<string, any> = {
}),
meta: undefined,
},
+ "pixel-image": {
+ name: "pixel-image",
+ description:
+ "A component that displays an image with a pixelated effect, creating a retro aesthetic.",
+ type: "registry:ui",
+ registryDependencies: undefined,
+ files: [
+ {
+ path: "registry/magicui/pixel-image.tsx",
+ type: "registry:ui",
+ target: "components/magicui/pixel-image.tsx",
+ },
+ ],
+ component: React.lazy(async () => {
+ const mod = await import("@/registry/magicui/pixel-image.tsx");
+ const exportName =
+ Object.keys(mod).find(
+ (key) =>
+ typeof mod[key] === "function" || typeof mod[key] === "object",
+ ) || item.name;
+ return { default: mod.default || mod[exportName] };
+ }),
+ meta: undefined,
+ },
"magic-card-demo": {
name: "magic-card-demo",
description:
@@ -4442,6 +4466,29 @@ export const Index: Record<string, any> = {
}),
meta: undefined,
},
+ "pixel-image-demo": {
+ name: "pixel-image-demo",
+ description: "Example showing a pixelated image effect.",
+ type: "registry:example",
+ registryDependencies: ["pixel-image"],
+ files: [
+ {
+ path: "registry/example/pixel-image-demo.tsx",
+ type: "registry:example",
+ target: "components/pixel-image-demo.tsx",
+ },
+ ],
+ component: React.lazy(async () => {
+ const mod = await import("@/registry/example/pixel-image-demo.tsx");
+ const exportName =
+ Object.keys(mod).find(
+ (key) =>
+ typeof mod[key] === "function" || typeof mod[key] === "object",
+ ) || item.name;
+ return { default: mod.default || mod[exportName] };
+ }),
+ meta: undefined,
+ },
utils: {
name: "utils",
description: "",
diff --git a/config/docs.ts b/config/docs.ts
index bc16692c..f3c8deff 100644
--- a/config/docs.ts
+++ b/config/docs.ts
@@ -344,6 +344,12 @@ export const docsConfig: DocsConfig = {
items: [],
label: "",
},
+ {
+ title: "Pixel Image",
+ href: "/docs/components/pixel-image",
+ items: [],
+ label: "New",
+ },
],
},
{
diff --git a/content/docs/components/pixel-image.mdx b/content/docs/components/pixel-image.mdx
new file mode 100644
index 00000000..94880ca8
--- /dev/null
+++ b/content/docs/components/pixel-image.mdx
@@ -0,0 +1,103 @@
+---
+title: Pixel Image
+date: 2025-06-05
+description: A component that displays your image with a pixelated effect, enhancing the visual appeal of any image in your website.
+author: dharminnagar
+published: true
+---
+
+<ComponentPreview name="pixel-image-demo" />
+
+## Features
+
+- Pixelated image reveal animation
+- Customizable grid size and layout
+- Supports grayscale-to-color animation
+- Adjustable animation duration and delay
+- Lightweight and easy to use
+
+## Installation
+
+<Tabs defaultValue="cli">
+
+<TabsList>
+ <TabsTrigger value="cli">CLI</TabsTrigger>
+ <TabsTrigger value="manual">Manual</TabsTrigger>
+</TabsList>
+<TabsContent value="cli">
+
+```bash
+npx shadcn@latest add "https://magicui.design/r/pixel-image"
+```
+
+</TabsContent>
+
+<TabsContent value="manual">
+
+<Steps>
+
+<Step>Copy and paste the following code into your project.</Step>
+
+<ComponentSource name="pixel-image" />
+
+<Step>Add the component to your page or layout.</Step>
+
+```tsx
+import PixelImage from "@/registry/magicui/pixel-image";
+
+export default function Page() {
+ return (
+ <PixelImage
+ src="/pixel-image-demo.jpg"
+ grid="6x4"
+ grayscaleAnimation={true}
+ />
+ );
+}
+```
+
+</Steps>
+
+</TabsContent>
+
+</Tabs>
+
+## Usage
+
+```tsx
+import PixelImage from "@/registry/magicui/pixel-image";
+```
+
+```tsx
+<PixelImage src="/pixel-image-demo.jpg" grid="8x8" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------------- | ------------------------------------------- | ------- | ---------------------------------------------- |
+| `src` | `string` | — | The image source URL |
+| `grid` | `"6x4" \| "8x8" \| "8x3" \| "4x6" \| "3x8"` | `"8x8"` | Predefined grid layout |
+| `customGrid` | `{ rows: number; cols: number; }` | — | Custom grid layout (overrides `grid`) |
+| `grayscaleAnimation` | `boolean` | `true` | Whether to animate from grayscale to color |
+| `pixelFadeInDuration` | `number` | `1000` | Duration (ms) for each pixel fade-in animation |
+| `maxAnimationDelay` | `number` | `1200` | Maximum random delay (ms) for pixel animation |
+| `colorRevealDelay` | `number` | `1500` | Delay (ms) before revealing color |
+
+### Grid Type
+
+```typescript
+// Predefined grid options
+"6x4" | "8x8" | "8x3" | "4x6" | "3x8"
+
+// Custom grid example
+customGrid={{ rows: 5, cols: 10 }}
+```
+
+## Note
+
+- Since the pixelation effect is purely decorative, make sure to provide text alternatives (like descriptions or labels) for any important content shown in the image. This ensures the content is accessible to screen reader users.
+
+## Credits
+
+- Credit to [@dharminnagar](https://x.com/dharminnagar) for implementation
diff --git a/public/pixel-image-demo.jpg b/public/pixel-image-demo.jpg
new file mode 100644
index 00000000..5c177e3e
Binary files /dev/null and b/public/pixel-image-demo.jpg differ
diff --git a/public/r/pixel-image-demo.json b/public/r/pixel-image-demo.json
new file mode 100644
index 00000000..8b7559d0
--- /dev/null
+++ b/public/r/pixel-image-demo.json
@@ -0,0 +1,18 @@
+{
+ "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+ "name": "pixel-image-demo",
+ "type": "registry:example",
+ "title": "Pixel Image Demo",
+ "description": "Example showing a pixelated image effect.",
+ "registryDependencies": [
+ "pixel-image"
+ ],
+ "files": [
+ {
+ "path": "registry/example/pixel-image-demo.tsx",
+ "content": "import PixelImage from \"@/registry/magicui/pixel-image\";\n\nexport default function Home() {\n return (\n <div>\n <PixelImage\n src=\"/pixel-image-demo.jpg\"\n customGrid={{ rows: 4, cols: 6 }}\n grayscaleAnimation={true}\n />\n </div>\n );\n}\n",
+ "type": "registry:example",
+ "target": "components/pixel-image-demo.tsx"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/public/r/pixel-image.json b/public/r/pixel-image.json
new file mode 100644
index 00000000..27c9e4e8
--- /dev/null
+++ b/public/r/pixel-image.json
@@ -0,0 +1,15 @@
+{
+ "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+ "name": "pixel-image",
+ "type": "registry:ui",
+ "title": "Pixel Image",
+ "description": "A component that displays an image with a pixelated effect, creating a retro aesthetic.",
+ "files": [
+ {
+ "path": "registry/magicui/pixel-image.tsx",
+ "content": "\"use client\";\nimport Image from \"next/image\";\nimport { useEffect, useState } from \"react\";\n\ntype Grid = {\n rows: number;\n cols: number;\n};\n\nconst DEFAULT_GRIDS: Record<string, Grid> = {\n \"6x4\": { rows: 4, cols: 6 },\n \"8x8\": { rows: 8, cols: 8 },\n \"8x3\": { rows: 3, cols: 8 },\n \"4x6\": { rows: 6, cols: 4 },\n \"3x8\": { rows: 8, cols: 3 },\n};\n\ntype PredefinedGridKey = keyof typeof DEFAULT_GRIDS;\n\ninterface PixelImageProps {\n src: string;\n grid?: PredefinedGridKey;\n customGrid?: Grid;\n grayscaleAnimation?: boolean;\n pixelFadeInDuration?: number; // in ms\n maxAnimationDelay?: number; // in ms\n colorRevealDelay?: number; // in ms\n}\n\nconst PixelImage = ({\n src,\n grid = \"6x4\",\n grayscaleAnimation = true,\n pixelFadeInDuration = 1000,\n maxAnimationDelay = 1200,\n colorRevealDelay = 1500,\n customGrid,\n}: PixelImageProps) => {\n const [isVisible, setIsVisible] = useState(false);\n const [showColor, setShowColor] = useState(false);\n\n const MIN_GRID = 1;\n const MAX_GRID = 16;\n\n const isValidGrid = (grid?: Grid) => {\n if (!grid) return false;\n const { rows, cols } = grid;\n return (\n Number.isInteger(rows) &&\n Number.isInteger(cols) &&\n rows >= MIN_GRID &&\n cols >= MIN_GRID &&\n rows <= MAX_GRID &&\n cols <= MAX_GRID\n );\n };\n\n const { rows, cols } = isValidGrid(customGrid)\n ? customGrid!\n : DEFAULT_GRIDS[grid];\n const total = rows * cols;\n\n useEffect(() => {\n setIsVisible(true);\n const colorTimeout = setTimeout(() => {\n setShowColor(true);\n }, colorRevealDelay);\n return () => clearTimeout(colorTimeout);\n }, [colorRevealDelay]);\n\n const pieces = Array.from({ length: total }, (_, index) => {\n const row = Math.floor(index / cols);\n const col = index % cols;\n\n const clipPath = `polygon(\n ${col * (100 / cols)}% ${row * (100 / rows)}%,\n ${(col + 1) * (100 / cols)}% ${row * (100 / rows)}%,\n ${(col + 1) * (100 / cols)}% ${(row + 1) * (100 / rows)}%,\n ${col * (100 / cols)}% ${(row + 1) * (100 / rows)}%\n )`;\n\n const delay = Math.random() * maxAnimationDelay;\n return {\n clipPath,\n delay,\n };\n });\n\n return (\n <div className=\"w-72 h-72 md:w-96 md:h-96 relative select-none\">\n {pieces.map((piece, index) => (\n <div\n key={index}\n className={`absolute inset-0 transition-all ease-out ${\n isVisible ? \"opacity-100\" : \"opacity-0\"\n }`}\n style={{\n clipPath: piece.clipPath,\n transitionDelay: `${piece.delay}ms`,\n transitionDuration: `${pixelFadeInDuration}ms`,\n }}\n >\n <Image\n src={src}\n fill\n alt={`Pixel image piece ${index + 1}`}\n className={`object-cover rounded-[2.5rem] transition-all z-1 ${grayscaleAnimation ? `duration-[${pixelFadeInDuration}ms]` : \"\"} ${\n grayscaleAnimation\n ? showColor\n ? \"grayscale-0\"\n : \"grayscale\"\n : \"\"\n }`}\n draggable={false}\n />\n </div>\n ))}\n </div>\n );\n};\n\nexport default PixelImage;\n",
+ "type": "registry:ui",
+ "target": "components/magicui/pixel-image.tsx"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/public/registry.json b/public/registry.json
index 5b8a8c40..07bf7755 100644
--- a/public/registry.json
+++ b/public/registry.json
@@ -1270,6 +1270,19 @@
}
]
},
+ {
+ "name": "pixel-image",
+ "type": "registry:ui",
+ "title": "Pixel Image",
+ "description": "A component that displays an image with a pixelated effect, creating a retro aesthetic.",
+ "files": [
+ {
+ "path": "registry/magicui/pixel-image.tsx",
+ "type": "registry:ui",
+ "target": "components/magicui/pixel-image.tsx"
+ }
+ ]
+ },
{
"name": "magic-card-demo",
"type": "registry:example",
@@ -3253,6 +3266,22 @@
}
]
},
+ {
+ "name": "pixel-image-demo",
+ "type": "registry:example",
+ "title": "Pixel Image Demo",
+ "description": "Example showing a pixelated image effect.",
+ "registryDependencies": [
+ "pixel-image"
+ ],
+ "files": [
+ {
+ "path": "registry/example/pixel-image-demo.tsx",
+ "type": "registry:example",
+ "target": "components/pixel-image-demo.tsx"
+ }
+ ]
+ },
{
"name": "utils",
"type": "registry:lib",
diff --git a/registry.json b/registry.json
index 5b8a8c40..07bf7755 100644
--- a/registry.json
+++ b/registry.json
@@ -1270,6 +1270,19 @@
}
]
},
+ {
+ "name": "pixel-image",
+ "type": "registry:ui",
+ "title": "Pixel Image",
+ "description": "A component that displays an image with a pixelated effect, creating a retro aesthetic.",
+ "files": [
+ {
+ "path": "registry/magicui/pixel-image.tsx",
+ "type": "registry:ui",
+ "target": "components/magicui/pixel-image.tsx"
+ }
+ ]
+ },
{
"name": "magic-card-demo",
"type": "registry:example",
@@ -3253,6 +3266,22 @@
}
]
},
+ {
+ "name": "pixel-image-demo",
+ "type": "registry:example",
+ "title": "Pixel Image Demo",
+ "description": "Example showing a pixelated image effect.",
+ "registryDependencies": [
+ "pixel-image"
+ ],
+ "files": [
+ {
+ "path": "registry/example/pixel-image-demo.tsx",
+ "type": "registry:example",
+ "target": "components/pixel-image-demo.tsx"
+ }
+ ]
+ },
{
"name": "utils",
"type": "registry:lib",
diff --git a/registry/example/pixel-image-demo.tsx b/registry/example/pixel-image-demo.tsx
new file mode 100644
index 00000000..61d14650
--- /dev/null
+++ b/registry/example/pixel-image-demo.tsx
@@ -0,0 +1,13 @@
+import PixelImage from "@/registry/magicui/pixel-image";
+
+export default function Home() {
+ return (
+ <div>
+ <PixelImage
+ src="/pixel-image-demo.jpg"
+ customGrid={{ rows: 4, cols: 6 }}
+ grayscaleAnimation={true}
+ />
+ </div>
+ );
+}
diff --git a/registry/magicui/pixel-image.tsx b/registry/magicui/pixel-image.tsx
new file mode 100644
index 00000000..b98dc3fe
--- /dev/null
+++ b/registry/magicui/pixel-image.tsx
@@ -0,0 +1,128 @@
+"use client";
+import { cn } from "@/lib/utils";
+import Image from "next/image";
+import { memo, useEffect, useMemo, useState } from "react";
+
+type Grid = {
+ rows: number;
+ cols: number;
+};
+
+const DEFAULT_GRIDS: Record<string, Grid> = {
+ "6x4": { rows: 4, cols: 6 },
+ "8x8": { rows: 8, cols: 8 },
+ "8x3": { rows: 3, cols: 8 },
+ "4x6": { rows: 6, cols: 4 },
+ "3x8": { rows: 8, cols: 3 },
+};
+
+type PredefinedGridKey = keyof typeof DEFAULT_GRIDS;
+
+interface PixelImageProps {
+ src: string;
+ grid?: PredefinedGridKey;
+ customGrid?: Grid;
+ grayscaleAnimation?: boolean;
+ pixelFadeInDuration?: number; // in ms
+ maxAnimationDelay?: number; // in ms
+ colorRevealDelay?: number; // in ms
+}
+
+const PixelImage = ({
+ src,
+ grid = "6x4",
+ grayscaleAnimation = true,
+ pixelFadeInDuration = 1000,
+ maxAnimationDelay = 1200,
+ colorRevealDelay = 1300,
+ customGrid,
+}: PixelImageProps) => {
+ const [isVisible, setIsVisible] = useState(false);
+ const [showColor, setShowColor] = useState(false);
+
+ const MIN_GRID = 1;
+ const MAX_GRID = 16;
+
+ const { rows, cols } = useMemo(() => {
+ const isValidGrid = (grid?: Grid) => {
+ if (!grid) return false;
+ const { rows, cols } = grid;
+ return (
+ Number.isInteger(rows) &&
+ Number.isInteger(cols) &&
+ rows >= MIN_GRID &&
+ cols >= MIN_GRID &&
+ rows <= MAX_GRID &&
+ cols <= MAX_GRID
+ );
+ };
+
+ return isValidGrid(customGrid) ? customGrid! : DEFAULT_GRIDS[grid];
+ }, [customGrid, grid]);
+
+ useEffect(() => {
+ setIsVisible(true);
+ const colorTimeout = setTimeout(() => {
+ setShowColor(true);
+ }, colorRevealDelay);
+ return () => clearTimeout(colorTimeout);
+ }, [colorRevealDelay]);
+
+ const pieces = useMemo(() => {
+ const total = rows * cols;
+ return Array.from({ length: total }, (_, index) => {
+ const row = Math.floor(index / cols);
+ const col = index % cols;
+
+ const clipPath = `polygon(
+ ${col * (100 / cols)}% ${row * (100 / rows)}%,
+ ${(col + 1) * (100 / cols)}% ${row * (100 / rows)}%,
+ ${(col + 1) * (100 / cols)}% ${(row + 1) * (100 / rows)}%,
+ ${col * (100 / cols)}% ${(row + 1) * (100 / rows)}%
+ )`;
+
+ const delay = Math.random() * maxAnimationDelay;
+ return {
+ clipPath,
+ delay,
+ };
+ });
+ }, [rows, cols, maxAnimationDelay]);
+
+ return (
+ <div className="relative h-72 w-72 select-none md:h-96 md:w-96">
+ {pieces.map((piece, index) => (
+ <div
+ key={index}
+ className={cn(
+ "absolute inset-0 transition-all ease-out",
+ isVisible ? "opacity-100" : "opacity-0",
+ )}
+ style={{
+ clipPath: piece.clipPath,
+ transitionDelay: `${piece.delay}ms`,
+ transitionDuration: `${pixelFadeInDuration}ms`,
+ }}
+ >
+ <Image
+ src={src}
+ fill
+ alt={`Pixel image piece ${index + 1}`}
+ className={cn(
+ "z-1 object-cover rounded-[2.5rem]",
+ grayscaleAnimation && (showColor ? "grayscale-0" : "grayscale"),
+ )}
+ style={{
+ transition: grayscaleAnimation
+ ? `filter ${pixelFadeInDuration}ms cubic-bezier(0.4, 0, 0.2, 1)`
+ : "none",
+ }}
+ draggable={false}
+ />
+ </div>
+ ))}
+ </div>
+ );
+};
+
+export default memo(PixelImage);
diff --git a/registry/registry-examples.ts b/registry/registry-examples.ts
index 8ba67684..904f77ce 100644
--- a/registry/registry-examples.ts
+++ b/registry/registry-examples.ts
@@ -1737,4 +1737,18 @@ export const examples: Registry["items"] = [
},
],
},
+ {
+ name: "pixel-image-demo",
+ type: "registry:example",
+ title: "Pixel Image Demo",
+ description: "Example showing a pixelated image effect.",
+ registryDependencies: ["pixel-image"],
+ files: [
+ {
+ path: "registry/example/pixel-image-demo.tsx",
+ type: "registry:example",
+ target: "components/pixel-image-demo.tsx",
+ },
+ ],
+ },
];
diff --git a/registry/registry-ui.ts b/registry/registry-ui.ts
index 9f95e73d..1a2489e0 100644
--- a/registry/registry-ui.ts
+++ b/registry/registry-ui.ts
@@ -1202,4 +1202,18 @@ export const ui: Registry["items"] = [
},
],
},
+ {
+ name: "pixel-image",
+ type: "registry:ui",
+ title: "Pixel Image",
+ description:
+ "A component that displays an image with a pixelated effect, creating a retro aesthetic.",
+ files: [
+ {
+ path: "registry/magicui/pixel-image.tsx",
+ type: "registry:ui",
+ target: "components/magicui/pixel-image.tsx",
+ },
+ ],
+ },
];