Skip to main content

Adding Books to Wishlists

BookWish offers multiple convenient ways to add books to your wishlists. Whether you know exactly what you want or you're browsing for inspiration, there's a method that works for you.

Search for Books​

The most common way to add books is through the search feature.

  1. Open Search:

    • Tap the search icon (magnifying glass) in any wishlist
    • Or go to the main search page from navigation

  2. Enter Search Terms:

    • Type the book title, author name, or ISBN
    • Search updates automatically as you type (debounced by 500ms)

  3. View Results:

    • Books appear with cover images, titles, and authors
    • Results are grouped by type (Books, People, Stores, etc.)
    • Tap any book to see full details

  4. Add to Wishlist:

    • In the book detail overlay, select a wishlist
    • Choose reading status (Want to Read, Currently Reading, Finished)
    • Set priority (High, Normal, Low)
    • Tap "Add" to confirm

Code Reference: Search implementation in /app/lib/ui/pages/search_page.dart.

Search Tips​

Search by Title​

  • ✅ "Project Hail Mary"
  • ✅ "hail mary" (partial titles work)
  • ✅ "project hail" (first words work well)

Search by Author​

  • ✅ "Andy Weir"
  • ✅ "Weir" (last name only)
  • ✅ "A. Weir" (initials work)

Search by ISBN​

  • ✅ "9780593135204" (ISBN-13)
  • ✅ "0593135202" (ISBN-10)
  • ✅ "978-0-593-13520-4" (with hyphens)
Search Debouncing

BookWish waits 500ms after you stop typing before searching. This prevents excessive API calls and provides a smoother experience.

Barcode Scanner​

The fastest way to add physical books is by scanning their ISBN barcode.

How to Scan Barcodes​

  1. Enable Scanner:

    • Open the search page
    • Tap the QR code icon in the search bar
    • Grant camera permission if prompted

  2. Position the Barcode:

    • Point your camera at the ISBN barcode
    • Usually found on the back cover near the bottom
    • Keep the camera steady and well-lit

  3. Automatic Detection:

    • The scanner detects barcodes instantly
    • No need to tap a capture button
    • The book details load automatically

  4. Add to Wishlist:

    • Review the book information
    • Select your wishlist and preferences
    • Tap "Add"

Code Reference: Barcode scanning in /app/lib/ui/pages/search_page.dart (lines 90-110, 489-530).

Scanner Features​

  • No duplicate detection: Scans each barcode only once
  • Instant lookup: Results appear immediately after scan
  • Guidance overlay: "Point camera at ISBN barcode" message
  • Exit anytime: Tap back or search bar to close scanner
ISBN Barcodes

Most modern books have a 13-digit ISBN barcode (EAN). Look for barcodes that start with "978" or "979" - these are book ISBNs.

Quick Add from Discovery​

While browsing BookWish, you can quickly add books without leaving your current view.

From Lines and Reviews​

When you see someone share a Line (quote) or Review:

  1. Tap the book cover or title in the post
  2. The book detail overlay appears
  3. Tap "Add to Wishlist"
  4. Select wishlist and preferences
  5. Continue browsing

From User Profiles​

When viewing another user's profile or wishlists:

  1. Tap a book that interests you
  2. Book details open
  3. Add to your own wishlist
  4. The book is copied to your list (doesn't affect theirs)

From Store Inventory​

While browsing a store's catalog:

  1. Find books in stock at local stores
  2. Tap to view details
  3. Add to wishlist for later purchase
  4. Optionally enable stock alerts

Adding from Book Info Overlay​

The book info overlay is your detailed view of any book.

Overlay Features​

When you tap a book, you'll see:

Book Details​

  • Full cover image
  • Complete title and subtitle
  • All authors
  • Publisher and publication date
  • Page count
  • ISBN numbers
  • Description/synopsis

Actions Available​

  • Add to Wishlist - primary action button
  • Share - send to friends
  • View Reviews - see what others think
  • Check Availability - see local store stock

Adding Process​

  1. Tap "Add to Wishlist"
  2. Choose a wishlist from your list
  3. Set reading status:
    • Want to Read (default)
    • Currently Reading
    • Finished
  4. Set priority (optional):
    • High (marked with red star)
    • Normal (default)
    • Low (marked with yellow star)
  5. Tap "Add" to confirm
First Wishlist Add

Browser the cat celebrates your first addition with: "Great choice! I'll keep track of this for you." This hint appears only once.

Code: See /app/lib/state/wishlist_provider.dart (lines 87-105).

Code Reference: Book info overlay in /app/lib/ui/overlays/book_info_overlay.dart.

Adding Multiple Books​

To add several books quickly:

Batch Adding Strategy​

  1. Search and queue:

    • Keep the search page open
    • Search for each book
    • Add each to your wishlist
    • The search stays active

  2. Use search filters:

    • Filter by "Books" only for focused results
    • Avoid mixed results (people, stores, etc.)

  3. Work from a physical list:

    • Use the barcode scanner for speed
    • Scan multiple books in sequence
    • Each scan automatically searches

Organized Addition​

For systematic collection building:

  1. Create wishlists first (by genre, theme, etc.)
  2. Add books to appropriate lists as you find them
  3. Use priority and status to organize
  4. Review and reorganize later

Search Filters​

Narrow down results using type filters:

Available Filters​

  • Books - novels, non-fiction, all book types
  • People - authors and readers
  • Stores - independent bookstores
  • Clubs - reading groups
  • Challenges - community reading challenges
  • Lines - shared quotes from books

Using Filters​

  1. Type your search query
  2. Tap filter chips below the search bar
  3. Select one or more types
  4. Results update automatically
  5. Clear filters by tapping "All" or deselecting all

Code Reference: Filter chips in /app/lib/ui/pages/search_page.dart (lines 175-193).

Handling Duplicates​

BookWish prevents duplicate books in the same wishlist:

  • If you try to add a book already in the list, you'll see a notice
  • The existing entry remains unchanged
  • You can update the existing entry's status/priority instead

To add a book to multiple wishlists:

  • Add it to the first wishlist
  • Then add it to additional wishlists
  • Each wishlist maintains separate status and priority

Search Result Details​

Book Tiles Show​

  • Cover image (or placeholder icon if unavailable)
  • Book title (truncated to 2 lines)
  • Authors (comma-separated, truncated to 1 line)
  • Tap target - entire tile is clickable

Result Grouping​

Search results are organized by type:

  • "Books - X results"
  • "People - X results"
  • Each group is separated by dividers

Code Reference: Result rendering in /app/lib/ui/pages/search_page.dart (lines 280-317).

Troubleshooting​

Book Not Found​

If your search returns no results:

  1. Check spelling - try alternative spellings
  2. Try the author instead of title
  3. Use ISBN if you have the book physically
  4. Search partial title - just the first few words

Scanner Not Working​

If the barcode scanner has issues:

  1. Check camera permission - grant if denied
  2. Improve lighting - good light helps detection
  3. Hold steady - keep camera stable
  4. Try manual ISBN - type it in search instead
  5. Clean the barcode - ensure it's not damaged

Wrong Book Appears​

If the wrong book shows up:

  1. Verify ISBN - some editions share ISBNs
  2. Check edition - you might have found a different version
  3. Search by title + author for the exact edition
  4. Check publication year in the description

Performance Optimizations​

BookWish optimizes the search experience:

  • Waits 500ms after you stop typing
  • Prevents excessive API calls
  • Provides smoother performance

Code: Debounce timer in /app/lib/ui/pages/search_page.dart (lines 60-65).

Cached Images​

  • Book covers are cached locally
  • Faster display on repeated views
  • Reduces data usage

Efficient Scanning​

  • No duplicate barcode detection
  • Immediate scanner dismissal after scan
  • Controller disposal to free resources

Next Steps​

After adding books to your wishlists: