🔍 expo-pixel-perfect

Perfect pixel-art scaling for your Expo apps. No blur, no artifacts - just crisp, clean pixels.

✨ Features

• Crisp nearest-neighbor scaling (no blurry pixels!)
• Advanced fractional scaling for non-integer scale factors
• Works with local, remote, and base64 images
• Platform-specific rendering modes (software/hardware) for quality vs performance
• Native performance
• Loading states with customizable components
• Error handling with fallback options
• Type-safe with full TypeScript support
• Zero configuration needed

🛠️ Supported Platforms

Platform	Supported
iOS	✅ New Architecture
Android	✅ New Architecture
Web	❌

Note: This module requires the New Architecture (Fabric) to be enabled in your Expo project. It will not work with the old architecture.

Web Platform: This module uses native implementations for pixel-perfect scaling and does not support web platforms. For web-specific pixel art needs, consider using CSS solutions or a web-specific library.

📦 Installation

1npx expo install expo-pixel-perfect

🚀 Usage

Basic Usage

1import ExpoPixelPerfectView from 'expo-pixel-perfect';
2
3export default function Game() {
4    return (
5        <ExpoPixelPerfectView
6            source={require('./assets/sprite.png')}
7            scale={4}
8        />
9    );
10}

Advanced Usage

1import ExpoPixelPerfectView from 'expo-pixel-perfect';
2
3export default function Game() {
4    return (
5        <ExpoPixelPerfectView
6            // Source image
7            source={require('./assets/sprite.png')}
8            
9            // Scale to specific width
10            scale={{ targetWidth: 64 }}
11            
12            // Use optimized algorithm for non-integer scaling
13            scaleMode="fractional-optimized"
14            
15            // Platform-specific rendering modes
16            android_renderMode="software"  // Higher quality on Android
17            ios_renderMode="software"      // Higher quality on iOS
18            
19            // Custom loading component
20            loadingComponent={<CustomLoader />}
21            
22            // Error handling
23            fallback={<Text>Failed to load sprite</Text>}
24            onError={(error) => console.error('Failed to load:', error)}
25            
26            // Load callback
27            onLoad={() => console.log('Sprite loaded successfully')}
28            
29            // Standard React Native styles
30            style={styles.sprite}
31        />
32    );
33}

Using Base64 Images

1import ExpoPixelPerfectView from 'expo-pixel-perfect';
2
3export default function Game() {
4    // Base64 encoded pixel art
5    const pixelArtBase64 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...';
6    
7    return (
8        <ExpoPixelPerfectView
9            source={{
10                base64: pixelArtBase64,
11                width: 16,  // Original width is required
12                height: 16  // Original height is required
13            }}
14            scale={3}
15        />
16    );
17}

Responsive Game UI

1import ExpoPixelPerfectView from 'expo-pixel-perfect';
2import { useWindowDimensions } from 'react-native';
3
4export default function ResponsiveGameElement() {
5    const { width } = useWindowDimensions();
6    const spriteOriginalWidth = 32;
7    
8    // Calculate a non-integer scale factor to fit screen width
9    const scaleFactor = width / spriteOriginalWidth / 2; // Fit 2 sprites side by side
10    
11    return (
12        <ExpoPixelPerfectView
13            source={require('./assets/game-element.png')}
14            scale={scaleFactor}
15            scaleMode="fractional-optimized" // Use optimized scaling for non-integer scales
16        />
17    );
18}

🎯 Props

Required Props

Prop	Type	Description
source	number | { uri: string } | { base64: string, width: number, height: number }	Image source (local, remote, or base64)

Optional Props

Prop	Type	Default	Description
scale	number | { targetWidth: number } | { targetHeight: number }	1	Scaling factor or target dimensions
style	ViewStyle	undefined	Standard React Native view styles
loadingComponent	ReactNode	null	Component shown during loading
fallback	ReactNode	null	Component shown on error
onError	(error: Error) => void	undefined	Error callback
onLoad	() => void	undefined	Success callback
scaleMode	"nearest" | "fractional-optimized"	"nearest"	Algorithm used for scaling
android_renderMode	"software" | "hardware"	"hardware"	Android-specific rendering mode
ios_renderMode	"software" | "hardware"	"hardware"	iOS-specific rendering mode

🖥️ Render Modes

This module provides platform-specific rendering modes to balance between visual quality and performance:

Android Render Modes

• software: Uses CPU-based rendering (View.LAYER_TYPE_SOFTWARE) for highest quality pixel-perfect rendering. Best for static UI elements or when visual quality is critical.
• hardware: Uses GPU-accelerated rendering (View.LAYER_TYPE_HARDWARE) for better performance. May have slightly less precise scaling but offers better battery life and performance.

iOS Render Modes

• software: Uses CoreGraphics (CPU-based) rendering with precise nearest-neighbor scaling. Best for static UI elements or when visual quality is critical.
• hardware: Uses Core Image (GPU-accelerated) rendering for better performance. May have slightly less precise scaling but offers better battery life and performance.

1// Example of platform-specific optimization
2<PixelImage
3    source={require('./assets/character.png')} 
4    scale={4}
5    // Use software rendering on Android for best quality
6    android_renderMode="software"
7    // Use hardware acceleration on iOS for better performance
8    ios_renderMode="hardware"
9/>

📏 Scaling Modes

This module offers two different scaling algorithms to handle different types of pixel art scaling:

Nearest Neighbor (scaleMode="nearest")

• Default scaling mode
• Best for integer scaling (2x, 3x, 4x, etc.)
• Fast and efficient
• May appear slightly blurry with non-integer scaling factors

Fractional-Optimized (scaleMode="fractional-optimized")

• Advanced scaling algorithm designed for non-integer scaling factors
• Uses a multi-step scaling process for sharper results
• Perfect for when you need to scale by factors like 1.5x, 2.3x, etc.
• Especially useful for responsive UIs or fitting to screen dimensions
• Uses more resources but produces significantly sharper results for fractional scales

1// Responsive UI with sharp pixel art
2<PixelImage
3    source={require('./assets/ui-element.png')} 
4    scale={deviceWidth / spriteWidth} // Non-integer scale to fit screen
5    scaleMode="fractional-optimized"
6/>

🎨 Tips

• Start with small source images (8x8, 16x16, 32x32)
• Use PNG format for transparency support
• For fixed sizes, use integer scales (2x, 3x) with "nearest" mode for best performance
• For responsive UI, use "fractional-optimized" mode with calculated scale factors
• Provide fallback components for better user experience
• Handle loading and error states for smoother UX
• Use "software" rendering mode for static UI elements for best quality
• Use "hardware" rendering mode for animated elements for better performance
• When using base64 images, always specify the original width and height, if you can't you could render it using a native image and getting its layout

🤔 Common Issues

Image appears blurry

Make sure you're using the correct scale factor. For a 16x16 image to display at 64x64, use either:

1scale={4}
2// or
3scale={{ targetWidth: 64 }}

For non-integer scaling that still looks crisp, use the fractional-optimized mode:

1scale={3.2} // Non-integer scale
2scaleMode="fractional-optimized"

If still blurry, try using the "software" rendering mode:

1android_renderMode="software"
2ios_renderMode="software"

Image not loading

Check that your asset path is correct and the image exists. The onError callback can help debug:

1onError={(error) => console.error('Loading failed:', error)}

Base64 image has wrong dimensions

When using base64 images, you must specify the original width and height:

1source={{
2    base64: myBase64String,
3    width: 16,   // Important! Must be exact
4    height: 16   // Important! Must be exact
5}}

Performance issues with fractional-optimized mode

1// This 
2<PixelImage
3    source={require('./assets/important-button.png')}
4    scale={2.5}
5    scaleMode="fractional-optimized" 
6/>
7
8// This will be slightly blurry
9<PixelImage
10    source={require('./assets/background-element.png')}
11    scale={2.5}
12    scaleMode="nearest" 
13/>

---

Made for ⚔️ Pixel Odyssey by Lino Iten