WallhavenDroid

A beautiful, fast, and feature-rich Android app for browsing and downloading wallpapers from Wallhaven.

---

Features

🖼️ Browse Wallpapers

• Latest - Browse newest wallpapers
• Toplist - View trending/popular wallpapers
• Random - Discover random wallpapers
• Infinite scroll - Load more as you scroll

🔍 Search & Filter

• Full-text search with tag support
• Filter by resolution, aspect ratio, color
• Category filters (General, Anime, People)
• Purity filters (SFW, Sketchy, NSFW)

⬇️ Download & Save

• One-tap download to gallery
• Set as wallpaper (Home/Lock/Both)
• Local favorites without API key
• Custom download notifications

📁 Collections

• View your Wallhaven collections
• Browse collection wallpapers
• Organize saved wallpapers

🎨 Design

• Material Design 3
• Dark/Light theme support
• Pinterest-style masonry grid
• Smooth animations and transitions
• Tab bar auto-hide on scroll

📁 Collections

• View your Wallhaven collections
• Browse collection wallpapers
• Organize saved wallpapers

🎨 Design

• Material Design 3
• Dark/Light theme support
• Pinterest-style masonry grid
• Smooth animations and transitions
• Hidden tab bar on scroll

⚙️ Settings

• API key configuration
• Theme preference (System/Light/Dark)
• Persistent settings

---

Screenshots

Browse	Search	Detail

---

Architecture

lib/
├── core/                    # Core utilities and constants
│   ├── constants/           # App colors, spacing, API constants
│   ├── theme/               # Light/Dark theme configuration
│   ├── extensions/          # String extensions
│   └── errors/              # Failure classes
├── data/                    # Data layer
│   ├── api/                 # API client (Dio)
│   ├── models/              # Freezed data models
│   └── repositories/         # Repository implementations
├── domain/                  # Domain layer
│   ├── entities/            # Search params, enums
│   └── repositories/        # Repository interfaces
├── features/                # Feature modules
│   ├── browse/              # Browse screen
│   ├── search/              # Search screen
│   ├── detail/              # Wallpaper detail screen
│   ├── favorites/           # Local favorites
│   ├── collections/         # Wallhaven collections
│   └── settings/            # App settings
├── services/                # Services (download, etc.)
├── providers/              # Riverpod providers
└── widgets/                # Reusable widgets
    └── common/              # WallpaperCard, WallpaperGrid, etc.

Architecture Pattern

• Clean Architecture with separation of concerns
• Riverpod for state management
• go_router for navigation
• freezed for immutable data models
• Repository Pattern for data access

---

Getting Started

Prerequisites

• Flutter SDK 3.x or higher
• Android SDK
• A Wallhaven account (optional, for NSFW content)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/wallhavendroid.git
   cd wallhavendroid

2. Install dependencies

   flutter pub get

3. Configure Android (Optional)

   If you encounter build issues, ensure your android/app/build.gradle has:

   android {
       compileOptions {
           coreLibraryDesugaringEnabled true
       }
   }

4. Run the app

   flutter run

Build APK

# Debug build
flutter build apk --debug

# Release build
flutter build apk --release

---

Configuration

API Key (Optional)

For accessing NSFW content:

1. Go to Wallhaven Settings
2. Generate an API key
3. Open the app → Settings → API Key
4. Enter your key

Permissions

The app requires:

• Storage - For saving wallpapers
• Photos/Media - For Android 13+ gallery access

---

Dependencies

Package	Purpose
flutter_riverpod	State management
go_router	Navigation & routing
freezed	Immutable data models
dio	HTTP client
cached_network_image	Image caching
flutter_staggered_grid_view	Masonry grid layout
share_plus	Share functionality
gal	Gallery integration
permission_handler	Runtime permissions
flutter_secure_storage	Secure storage for API key

---

API Reference

This app uses the Wallhaven API v1.

Endpoints Used

• GET /api/v1/search - Search wallpapers
• GET /api/v1/w/{id} - Get wallpaper details
• GET /api/v1/collections - User collections
• GET /api/v1/settings - User settings

Authentication

Pass API key via header:

X-API-Key: <your-api-key>

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• Wallhaven for the amazing wallpaper source
• Flutter for the cross-platform framework
• All contributors and maintainers of the open-source packages used

---

Support

• Issues: Report bugs or request features via GitHub Issues
• Email: contact@example.com

---

Made with ❤️ using Flutter