XPixelImage — Pixel Art Image

A Canvas-based pixel-art image conversion component. It downsamples any image and upscales it with nearest-neighbor sampling to produce a pixel-block effect, with adjustable pixel intensity and an optional color count limit.

Live Demo

加载中...

加载中...

加载中...

<XPixelImage src="/pixel-demo.png" :pixel-size="16" />

Props

Prop	Type	Default	Description
src	string	— (required)	Image URL: local path / network URL / base64 data URL all work
width	number	300	Display width (px)
height	number	300	Display height (px)
pixelSize	number	8	Pixel block size (2~64); larger means a stronger pixel effect
colorCount	number	0	Color count limit (0 = unlimited)
frame	boolean	true	Whether to show a pixel-style border

Pixel Intensity Reference

pixelSize	Effect
4	Fine, retains more detail
8	Medium, balances detail and pixel feel
16	Coarse, pixel blocks clearly visible
32	Minimal, keeps only color-block outlines

How It Works

1. Downsample: shrink to (width/pixelSize) × (height/pixelSize) with nearest-neighbor interpolation to keep hard edges.
2. Color quantization (optional): when colorCount is set, the RGB space is evenly divided into ∛colorCount levels and mapped to the nearest block.
3. Upscale: scale back to the target size with imageSmoothingEnabled = false to keep pixels sharp.

Usage Notes

• Changing src automatically reloads and re-pixelates.
• Large images + small pixelSize mean heavy intermediate computation — keep the dimensions reasonable.
• colorCount uses uniform quantization (not K-Means), which is faster.
• Images must support CORS, otherwise Canvas drawImage throws a security error.