Skip to main content
Open Mushaf Native automatically tracks your reading position and provides tools to save and return to your place in the Quran.

​
Reading Position Management

The app maintains two types of reading positions:
  1. Saved Reading Position: Your permanent bookmark (stored in currentSavedPage atom)
  2. Temporary Navigation: Pages you visit without changing your saved position

​
Current Saved Page

Your reading position is automatically saved when:
  • You navigate to a page without the temporary=true parameter
  • The page is within valid bounds (1 to total pages)
  • You’re not in temporary navigation mode
The saved page is stored in the currentSavedPage atom and persists using MMKV storage.

​
Reading Position Banner

When you navigate in temporary mode (e.g., from the navigation screen), a Reading Position Banner appears at the bottom of the screen. Component: components/ReadingPositionBanner.tsx The banner only appears when:
  • You’re in temporary navigation mode (temporary=true)
  • Your current page differs from your saved reading position
The Reading Position Banner shows: “العودة إلى موضع القراءة (صفحة X)” - “Return to reading position (Page X)“

​
Collapsible Design

The banner has two states:
Height: 60px (READING_BANNER_HEIGHT_CLOSED)Shows:
  • Return message with saved page number
  • Chevron-down icon
Tap to expand and reveal action buttons.
The expanded banner provides two actions:
1

Save Current Position (حفظ)

Primary Button with bookmark iconWhat it does:
  • Saves the current page as your reading position
  • Updates currentSavedPage to the current page
  • Updates yesterdayPage with current page and date
  • Removes the temporary parameter from the URL
  • Hides the banner
2

Return to Saved Position (العودة)

Outlined Button with arrow iconWhat it does:
  • Navigates back to your saved reading position
  • Removes the temporary parameter from the URL
  • Hides the banner

​
Using the Reading Position Banner

1

Browse Temporarily

Use the navigation screen to browse different pages. The banner appears automatically.
2

Expand Banner

Tap the banner to expand and see action buttons.
3

Choose Action

  • Tap حفظ (Save) to bookmark the current page
  • Tap العودة (Return) to go back to your saved position
The banner’s collapsed state is saved in readingBannerCollapsedState and persists across navigation.

​
Yesterday Page Tracking

The app tracks your reading position from the previous day.

​
How It Works

type PageWithDate = {
  value: number;  // Page number
  date: string;   // Date as string
};
The yesterdayPage atom stores:
  • value: Last saved page number
  • date: Date when it was saved

​
Automatic Reset

Using Jotai’s observe effect, the app:
  1. Checks if the stored date matches today’s date
  2. If the date changed (new day), updates yesterdayPage with:
    • Current currentSavedPage as the value
    • Today’s date
This happens automatically when the app launches.
Yesterday page is useful for daily reading trackers and progress monitoring.

​
Reading Position Hook

The useCurrentPage hook (hooks/useCurrentPage.ts) manages reading position logic.

​
Hook Return Values

return {
  currentPage,              // Current page being viewed
  currentSavedPage,         // Saved reading position
  setCurrentPage,           // Function to update reading position
  isTemporaryNavigation,    // Boolean: true if in temporary mode
};

​
Temporary Navigation Detection

The hook determines if you’re in temporary mode: 
const isTemporaryNavigation = 
  temporary === 'true' && parsedPage !== currentSavedPageValue;
Conditions:
  • URL has temporary=true parameter, AND
  • Current page differs from saved page

​
Saving Reading Position

The setCurrentPage function handles saving:
1

Validate Page Number

Ensures the page is within valid bounds:
  • Minimum: Page 1
  • Maximum: Total pages for selected Riwaya
2

Check Temporary Mode

If temporary=true, the function returns early without saving.
3

Update Saved Page

Sets currentSavedPage atom to the new page number.
4

Update Widget

Calls updateAndroidWidget() to sync with home screen widget (Android only).

​
Automatic Position Saving

Reading position is automatically saved when:

​
Page Load from URL

useEffect(() => {
  const parsedPage = parseInt(pageParam);
  if (!isNaN(parsedPage) && temporary !== 'true') {
    setCurrentSavedPageValue(parsedPage);
    updateAndroidWidget();
  }
}, [pageParam, setCurrentSavedPageValue, temporary]);
When you:
  • Navigate to a page via URL parameter
  • The temporary parameter is not 'true'
  • The page number is valid

​
Direct Navigation

When you navigate to a page without using the navigation screen:
  • The page is immediately saved as your reading position
  • No banner appears
  • The temporary parameter is absent from the URL

​
Integration with Daily Tracker

Reading position integrates with the daily tracker:
  • Yesterday Page: Starting point for tracking daily progress
  • Current Page: Used to calculate how much you’ve read today
  • Daily Goal: Compared against pages read since yesterday
See the Daily Tracker documentation for more details on progress tracking.

​
State Persistence

All reading position data is persisted using MMKV:
Type: numberDefault: 1Storage Key: 'CurrentSavedPage'Stores your current reading position.

​
Scenario 1: Casual Browsing

1

You're reading page 100

Current saved position: Page 100
2

Open navigation to check page 200

Navigate to page 200 with temporary=trueBanner appears showing “Return to reading position (Page 100)”
3

Return to reading

Tap “العودة” (Return) to go back to page 100

​
Scenario 2: Finding a New Position

1

You're reading page 100

Current saved position: Page 100
2

Navigate to page 200

Navigate with temporary=trueBanner appears
3

Save new position

Tap “حفظ” (Save) to bookmark page 200Your reading position updates to page 200, banner disappears

​
Scenario 3: Direct Navigation

1

Navigate without temporary mode

Navigate directly to page 200 (no temporary=true)
2

Position auto-saved

Page 200 becomes your saved reading position immediatelyNo banner appears

​
Accessibility

The Reading Position Banner includes full accessibility support:
  • Collapse Button: accessibilityLabel indicates expand/collapse state
  • Save Button:
    • accessibilityLabel: “حفظ موضع الحالي” (Save current position)
    • accessibilityHint: Shows current page number
  • Return Button:
    • accessibilityLabel: “العودة إلى موضع القراءة” (Return to reading position)
    • accessibilityHint: Shows saved page number
Screen readers will announce the current page, saved page, and available actions.

​
Best Practices

1

Regular Reading

Navigate directly to continue where you left off. Your position saves automatically.
2

Looking Up References

Use the navigation screen with temporary mode to check other pages without losing your place.
3

Marking Progress

When you finish a reading session at a new location, use the banner’s Save button to update your bookmark.

Build docs developers (and LLMs) love

Get started for freeTalk to us