Back to Blog
· 4 min read

Hafalan Qur'an — Juz Amma: A Minimal Ayah-by-Ayah Muraja'ah Tool

A single-page static web app built for Quran memorization practice. Browse Juz Amma surahs, play per-ayah recitation with configurable repeats and speed — no frameworks, no build tools, just pure HTML/CSS/JS.

Web JavaScript Quran Open Source
// table of contents (12 sections)

Try it live — The app is hosted on GitHub Pages and the source code is on GitHub. Bismillah!

Live Demo

You can try HafalanQuran right here — it’s fully functional embedded below:

Why I Built This

Memorizing the Qur’an (hifz) is a journey, but the real challenge is retention — muraja’ah (review). I needed a tool that:

  1. Plays one ayah at a time — not the whole surah, just the specific ayah I’m reviewing
  2. Supports range repeat — play ayah 1–5 on repeat until I nail them
  3. Adjustable speed — 0.5x for difficult passages, 2.0x for quick review
  4. Works offline-ready — no login, no account, no server. Open and start.

Most Qur’an apps play full surahs. For muraja’ah, you need granular ayah-level control. That’s exactly what this does.

Tech Stack (or Lack Thereof)

This project is deliberately minimal:

LayerChoiceWhy
UIVanilla HTML + CSS + JSZero dependencies, instant load
DataStatic JSON (juz_amma_arab_id.json)No API calls at runtime
AudioQur’an Foundation CDN (Minshawi Murattal)Free, high-quality recitation
StoragelocalStoragePersist theme + speed preference
BuildNoneJust serve the folder

The entire app lives in a single index.html file (~60KB including inline CSS and JS). The JSON data file contains all 37 surahs of Juz Amma with Arabic text and Indonesian translation.

Features

Per-Ayah Playback

Select any surah, choose an ayah range, and hit play. Each ayah highlights as it plays — so you can follow along visually while listening.

Configurable Repeat

Set how many times each ayah repeats before moving to the next. Perfect for drilling difficult passages.

Adjustable Speed

0.5x to 2.0x in 0.25 increments. Start slow, then speed up as your memorization strengthens.

Day/Night Mode

Dark mode by default (easy on the eyes during night muraja’ah sessions), with a warm light mode toggle. Your preference is saved in localStorage.

How It Works

The audio pipeline is straightforward:

  1. User selects a surah and ayah range
  2. App constructs audio URLs pointing to the Qur’an Foundation CDN: verses.quran.foundation/Minshawi/Murattal/mp3/{surah}{ayah}.mp3
  3. Audio plays sequentially with configurable repeat per ayah
  4. Currently playing ayah gets a visual highlight
  5. User can pause/resume at any point

The data flow:

juz_amma_arab_id.json
    ↓
index.html loads JSON
    ↓
Renders surah list + ayah display
    ↓
User picks range → audio plays from CDN
    ↓
Visual highlight syncs with playback

What I Learned

Building something with zero frameworks is refreshing. No build step, no bundle size worries, no dependency updates. Just HTML, CSS, and JavaScript working together.

Key takeaways:

  • Simplicity wins — For a focused tool like this, vanilla JS is more than enough
  • Audio API quirks — HTMLAudioElement doesn’t have a clean “onended” queue, so I built a simple sequential playback manager
  • CORS considerations — Remote audio CDN needs to allow cross-origin requests; the Qur’an Foundation CDN handles this well
  • localStorage for UX — Persisting theme and speed makes repeated use frictionless

Source Code

The project is open source:

Only 4 files in the repo:

HafalanQur-an/
├── index.html                          # The entire app
├── juz_amma_arab_id.json               # Surah data
├── generate_juz_amma_arab_id.js        # Data generator script
└── README.md                           # Documentation

Clone it, serve it with any static file server, and you’re good to go.

Possible Improvements

Some ideas for future enhancement:

  • Offline support — Cache audio files with Service Worker for true offline muraja’ah
  • Progress tracking — Mark surahs/ayahs as mastered and track review history
  • More reciters — Support different qari (Husary, Abdul Basit, etc.)
  • Full Qur’an — Expand beyond Juz Amma to all 30 juz
  • PWA — Make it installable on mobile home screen

Barakallahu feekum — may Allah bless your Qur’an memorization journey. 🤲

Comments