A simple yet elegant Vanilla JavaScript Quran web application displaying the authentic Mushaf Madina layout with QCF4 fonts.
Beautiful rendering of the Quran using QCF4 fonts with authentic Mushaf Madina layout
Easy navigation through Surahs and Juz with an elegant modal interface
Java Quran Web is a lightweight, pure JavaScript web application that renders the Holy Quran in the traditional Mushaf Madina format. The project focuses on simplicity, performance, and authentic visual representation using the industry-standard QCF4 (Quran Complex Fonts v4) font system.
- π Authentic Mushaf Layout - Pixel-perfect replication of the printed Mushaf Madina (604 pages)
- π¨ QCF4 Font System - Professional-grade fonts from King Fahd Complex for Printing the Holy Quran
- β‘ Zero Dependencies - Pure vanilla JavaScript, HTML, and CSS
- π± Responsive Design - Dynamic scaling using CSS Container Queries for all screen sizes
- π§ Easy Navigation - Browse by Surah, Juz, page number, or keyboard shortcuts
- π― Verse Highlighting - Interactive verse-level highlighting on hover
- π Tafseer & Translation - Instant access to Arabic Tafseer (Al-Muyassar) and English Translation (Saheeh Intl)
- π§ Audio Playback - Listen to verse recitation (Mishary Alafasy) directly from the Tafseer view
- π‘ External API - Public JavaScript API to navigate and highlight any ayah programmatically
- π URL Navigation - Direct linking to any page or specific ayah via URL parameters
- π RTL Support - Full right-to-left layout for Arabic text
- π Fast Loading - Dynamic font loading and efficient rendering
This project is built with pure web technologies, no frameworks required:
- HTML5 - Semantic markup and modern web standards
- CSS3 - Custom styling with CSS Grid and Flexbox
- Vanilla JavaScript (ES6+) - No frameworks, just clean modern JS
- QCF4 Fonts - Official Quran fonts in WOFF2 format
We chose vanilla JavaScript to:
- β Keep the project lightweight and fast
- β Avoid framework bloat and dependencies
- β Make the codebase accessible to all developers
- β Ensure long-term compatibility and maintainability
- β Focus on web fundamentals
Java-Quran-Web/
βββ index.html # Main HTML entry point
βββ css/
β βββ app.css # Main application styles
β βββ qcf4-fonts.css # QCF4 font declarations
βββ js/
β βββ app.js # Main application controller
β βββ data-loader.js # Data fetching and parsing
β βββ navigation.js # Navigation logic (optional)
β βββ renderer.js # Page rendering engine
βββ assets/
β βββ fonts/
β βββ qcf4/ # QCF4 font files (WOFF2)
β βββ kitab/ # Kitab font files (WOFF2)
βββ data/
βββ suwar.json # Surah metadata
βββ page_mapping.json # Page-to-verse mappings
βββ mushaf_metadata.json # Layout metadata
βββ quran_layout.csv # Glyph positioning data
- A modern web browser (Chrome, Firefox, Safari, Edge)
- A local web server (for development)
-
Clone the repository
git clone https://github.com/iTarek/Java-Quran-Web.git cd Java-Quran-Web -
Start a local server
# Using Python 3 python -m http.server 8000 # Using Node.js npx http-server # Using PHP php -S localhost:8000
-
Open in browser
Navigate to
http://localhost:8000in your browser.
- Arrow Buttons - Click the left/right arrows to navigate between pages
- Header/Footer Click - Click on the page header or footer to open the navigation modal
- Surah Navigation - Browse and jump to any Surah from the navigation menu
- Juz Navigation - Access any of the 30 Juz sections
You can navigate directly to any page using URL hashes:
http://localhost:8000/#page/1 # Al-Fatiha (Page 1)
http://localhost:8000/#page/293 # Al-Kahf (Page 293)
Navigate directly to any specific ayah with automatic page detection and highlighting:
http://localhost:8000/?surah=2&ayah=255 # Ayat Al-Kursi
http://localhost:8000/?s=36&a=1 # Surah Ya-Sin, Ayah 1
The ayah will be highlighted in yellow to distinguish it from hover highlights.
- Hover - Hover over any verse to see gray highlighting
- Click - Click any verse to open the Tafseer & Audio modal
- Persistent Highlight - Yellow highlighting for API/URL navigation
- Right Arrow - Go to previous page
- Left Arrow - Go to next page
- Space - Open navigation menu (Surah/Juz list)
- Escape - Close any open modal (Tafseer or Navigation)
Clicking on any ayah opens a modal with:
- Arabic Tafseer: Al-Tafseer Al-Muyassar (Ψ§ΩΨͺΩΨ³ΩΨ± Ψ§ΩΩ ΩΨ³Ψ±)
- English Translation: Saheeh International
- Audio Player: Listen to the verse recitation by Mishary Rashid Alafasy
- Click
βΆto play (icon turns green w/ red stop square) - Click
βto stop - Audio automatically stops when closing the modal
- Click
Java Quran Web exposes a public JavaScript API for integration with other applications:
// Navigate to Surah Al-Baqarah (2), Ayah 255 (Ayat Al-Kursi)
await quranApp.goToAyah(2, 255);
// Navigate with options
await quranApp.goToAyah(2, 255, {
persistent: true, // Keep highlight until cleared (default: true)
scroll: true // Scroll ayah into view (default: true)
});// Remove the yellow persistent highlight
quranApp.clearPersistentHighlight();// Highlight ayah on current page (gray, temporary)
quranApp.highlightAyah(surah, ayah);
// Remove all hover highlights
quranApp.removeAllHighlights();
// Get current page number
quranApp.currentPage; // e.g., 42
// Check if app is ready
quranApp.isReady; // true/false<iframe src="https://yourdomain.com/quran/?surah=2&ayah=255" width="100%" height="600"></iframe>Or programmatically after loading:
// Wait for app to initialize, then navigate
window.addEventListener('load', async () => {
await quranApp.goToAyah(2, 255);
});The main application controller that:
- Initializes the data loader and renderer
- Manages application state
- Handles navigation between pages
- Controls the overlay modal for navigation
Responsible for:
- Loading all Quran data files
- Parsing CSV layout data
- Providing data access methods
- Caching loaded data
Handles:
- Dynamic font loading
- Page layout rendering
- Glyph-by-glyph positioning
- Header and footer generation
- Verse grouping and highlighting
User Action β QuranApp β DataLoader β Renderer β DOM Update
- User navigates to a page
- QuranApp requests page data from DataLoader
- Renderer fetches layout data for that page
- Fonts are dynamically loaded if needed
- Page is rendered line-by-line with proper formatting
The application uses a carefully crafted color scheme inspired by traditional Quran manuscripts:
--primary-color: #2c5530; /* Dark green */
--secondary-color: #d4af37; /* Gold */
--bg-color: #faf8f3; /* Off-white */
--text-color: #1a1a1a; /* Near black */
--border-color: #e0d4b8; /* Beige */The application adapts to different screen sizes:
- Desktop: Full Mushaf page view
- Tablet: Optimized layout with touch controls
- Mobile: Single-column view with adjusted font sizes
The QCF4 fonts are vector-based fonts that encode:
- Arabic Quranic text glyphs
- Tajweed rules
- Pause marks (waqf signs)
- Verse endings (ayah markers)
- Chapter decorations (surah names)
Each glyph is mapped to a Unicode character in the Private Use Area (0xF100+).
The application renders all 604 pages of the Mushaf Madina:
- 15 lines per page - Exact match to printed Mushaf
- Dynamic line centering - Specific lines are centered per page
- Page headers - Display Surah name and Juz number
- Page footers - Show Arabic page numbers
- Basmalah placement - Special handling for "Ψ¨Ψ³Ω Ψ§ΩΩΩ Ψ§ΩΨ±ΨΩ Ω Ψ§ΩΨ±ΨΩΩ "
We need your help to make this better!
This is a simple, clean implementation, but there's always room for improvement. Here's how you can contribute:
- π Report Bugs - Found an issue? Open an issue
- π‘ Suggest Features - Have an idea? We'd love to hear it!
- π Improve Documentation - Help make the docs clearer
- π¨ Enhance Design - Improve the UI/UX
- β‘ Optimize Performance - Make it faster
- π§ͺ Add Tests - Help us build a test suite
- π Add Translations - Translate the interface to other languages
Please see the Roadmap (Version 2.0) for prioritized features such as Search, Bookmarking, Dark Mode, and Offline Support. We welcome community contributions for the following enhancements:
- Touch Gestures - Swipe navigation for mobile
- Print Optimization - Better print layouts
- Accessibility - Screen reader support and ARIA labels
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Test thoroughly
- Commit your changes (
git commit -m 'Add amazing feature') - Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Use clear, descriptive variable names
- Add comments for complex logic
- Follow existing code patterns
- Keep functions small and focused
- Test on multiple browsers
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
The QCF4 fonts are proprietary to the King Fahd Complex for the Printing of the Holy Quran. Please ensure you have the proper licensing to use these fonts in your project.
- King Fahd Complex - For the QCF4 font system
- All Contributors - For making this project better
| Browser | Version | Status |
|---|---|---|
| Chrome | 90+ | β Fully Supported |
| Firefox | 88+ | β Fully Supported |
| Safari | 14+ | β Fully Supported |
| Edge | 90+ | β Fully Supported |
| Opera | 76+ | β Fully Supported |
- Basic Mushaf rendering using QCF4 fonts
- Page navigation & Surah/Juz indexing
- Responsive layout with Container Queries
- Hover highlighting for verses
- Public JavaScript API (
goToAyah) - URL parameter navigation (
?surah=2&ayah=255) - Persistent highlighting (Yellow) vs Hover (Gray)
- Tafseer Modal (Arabic Al-Muyassar & English Saheeh)
- Audio Recitation (Verse-by-verse playback)
- Keyboard Navigation (Arrows & Space for Menu)
- Footer Navigation Controls
- Full Search functionality (Arabic & English)
- Bookmarking & Favorites system
- PWA (Progressive Web App) offline support
- Dark Mode / Themes
- Multiple Reciter options
If you find this project useful, please consider:
- β Starring the repository
- π Reporting bugs
- π¬ Sharing feedback
- π€ Contributing code
- π’ Spreading the word
Made with β€οΈ for the Muslim Ummah
Jazakum Allahu Khairan - May Allah reward you with goodness