Browse beautiful wallpapers from GitHub repositories with lightning-fast performance and elegant design
- Multiple Engines - Browse wallpapers from any public GitHub repository
- 11 Built-in Collections - Pre-configured repositories with thousands of wallpapers
- Custom Engines - Add your own favorite wallpaper repositories
- Easy Switching - Seamlessly switch between different wallpaper sources
- Masonry Layout - Beautiful, responsive grid that adapts to image sizes
- 3 Thumbnail Sizes - Choose between small, medium, or large grid views
- Category Navigation - Browse by organized categories
- Smart Sorting - Sort by name or file size, ascending or descending
- Powerful Search - Find wallpapers instantly by name or category
- Infinite Scroll - Smooth, lazy-loaded browsing experience
- Lightning Fast - 99.5% bandwidth reduction with optimized thumbnails
- Progressive Loading - Blur-to-sharp transitions for smooth experience
- Intelligent Caching - Per-engine data caching for instant switching
- Memory Efficient - 90% memory reduction vs loading full resolution
- Fullscreen Preview - View and download wallpapers in full quality
- Dark/Light Mode - Toggle themes with persistent preference
- Persistent Settings - All preferences saved (theme, size, sort, engine)
- Responsive Design - Works beautifully on all devices
- Keyboard Shortcuts - ESC to close modal, intuitive navigation
Built with modern web technologies for optimal performance:
- React 19 - Latest React with concurrent features
- TypeScript - Full type safety throughout the codebase
- Vite - Lightning-fast build tool and dev server
- Tailwind CSS v3 - Utility-first styling with custom theme
- Lucide React - Beautiful, customizable icons
- GitHub API - Direct repository integration
- wsrv.nl - Image optimization proxy
- Node.js 18+
- npm or yarn
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build
# Preview production build
npm run previewThe app will be available at http://localhost:5173/
wall-e-gallery/
├── src/
│ ├── components/ # React components
│ │ ├── Button.tsx
│ │ ├── Input.tsx
│ │ ├── Sidebar.tsx
│ │ ├── SearchBar.tsx
│ │ ├── MasonryGallery.tsx
│ │ ├── ImageModal.tsx
│ │ └── InfiniteScrollTrigger.tsx
│ ├── hooks/ # Custom React hooks
│ │ ├── useTheme.ts
│ │ └── useInfiniteScroll.ts
│ ├── lib/ # Utilities and services
│ │ ├── utils.ts
│ │ └── github-api.ts
│ ├── types/ # TypeScript type definitions
│ │ └── index.ts
│ ├── App.tsx # Main app component
│ ├── main.tsx # App entry point
│ └── index.css # Global styles
├── public/ # Static assets
└── ...config files
The app uses a sophisticated engine system to browse wallpapers from any GitHub repository:
- Engine Selection - Choose from built-in engines or add custom repositories
- Tree Fetching - GitHub API fetches the complete repository structure
- Smart Caching - Per-engine caching minimizes API calls and enables instant switching
- Image Optimization - Thumbnails generated on-the-fly via wsrv.nl proxy (10MB → 50KB)
- Progressive Loading - Gallery shows thumbnails, full-res loads only in modal
- Client-side Operations - All filtering, sorting, and searching happen instantly on cached data
GitHub API:
https://api.github.com/repos/{owner}/{repo}/git/trees/{sha}?recursive=1
Raw Images:
https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}
Optimized Thumbnails:
https://wsrv.nl/?url={encoded-url}&w={width}&q={quality}&output=webp
The app implements multiple performance strategies to handle large wallpaper collections efficiently:
- Image Proxy Service - Uses wsrv.nl to generate optimized thumbnails (400px width, 80% quality, WebP format)
- Progressive Loading - Displays thumbnails first, then loads full resolution only in modal
- Blur-to-Sharp Transition - Smooth visual effect during image loading
- Lazy Loading - Browser-native lazy loading with Intersection Observer
- WebP Format - Automatic conversion to WebP for better compression (50-80% smaller)
- Thumbnail-only Gallery - Gallery shows only 400px thumbnails, not full 4K+ images
- On-demand Full Resolution - Full res images loaded only when viewing in modal
- Virtual Scrolling Ready - Component architecture supports virtual scrolling for thousands of images
- Intersection Observer - Efficient viewport detection with 200px root margin
- React.memo & useMemo - Optimized re-renders
- Infinite Scroll - Loads 20 images at a time instead of all at once
- CSS Columns - Hardware-accelerated masonry layout (no JS calculation)
- Debounced Search - Prevents excessive filtering operations
- Repository Tree Caching - GitHub API response cached to minimize requests
- CDN Delivery - All images served through GitHub CDN and wsrv.nl proxy
- Parallel Loading - Multiple images load simultaneously
- Smart Preloading - Images preload just before entering viewport
- Bandwidth Savings - 99.5% reduction (10MB → 50KB per image)
- Memory Usage - 90% reduction with thumbnail-only gallery
- Initial Load - ~200ms framework load
- First Paint - < 1 second with thumbnails
Works on all modern browsers supporting:
- ES2020+ JavaScript features
- CSS Grid and Flexbox
- Intersection Observer API
- WebP image format
Contributions are welcome! Please read our Contributing Guide for details on:
- Setting up the development environment
- Code style guidelines
- Pull request process
This project is open source and available under the MIT License.
Built with ❤️ using React, TypeScript, and Tailwind CSS
⭐ Star this repo if you find it useful!