Comprehensive comparison of Quran Mushaf layouts available via Quran Foundation API.
Why?
| Property | Details |
|---|---|
| Mushaf ID | 1 |
| Font | Quran Complex Font V2 (QCF V2) |
| Type | Glyph-based (604 page-specific fonts) |
| Total Pages | 604 |
| Lines per Page | 15 |
| Source | Medina Mushaf (King Fahd Complex) |
| Status | ✅ Current/Recommended |
| Updates | Actively maintained |
Description:
Best For:
Font URL Pattern:
https://verses.quran.foundation/fonts/quran/hafs/v2/woff2/p{PAGE}.woff2
API Request:
curl -H "x-auth-token: TOKEN" \
"https://apis.quran.foundation/content/api/v4/verses/by_page/1?mushaf=1&words=true&word_fields=code_v2,text_qpc_hafs"
| Property | Details |
|---|---|
| Mushaf ID | 5 |
| Font | QPC Hafs (Unicode-based) |
| Type | Unicode (single font file) |
| Total Pages | 604 |
| Lines per Page | 15 |
| Source | King Fahd Quran Printing Complex |
| Status | ⚠️ Older/Legacy |
| Updates | Less frequent |
Description:
text_qpc_hafs field)Best For:
Font URL:
https://verses.quran.foundation/fonts/quran/hafs/uthmanic_hafs/UthmanicHafs1Ver18.woff2
API Request:
curl -H "x-auth-token: TOKEN" \
"https://apis.quran.foundation/content/api/v4/verses/by_page/1?mushaf=5&words=true&word_fields=text_qpc_hafs"
| Property | Details |
|---|---|
| Mushaf ID | 19 |
| Font | Quran Complex Font V4 Tajweed |
| Type | Glyph-based with color (604 page-specific fonts) |
| Total Pages | 604 |
| Lines per Page | 15 |
| Source | Medina Mushaf with Tajweed coloring |
| Status | ✅ Current (for Tajweed) |
| Updates | Actively maintained |
Description:
Best For:
Font URL Pattern (COLRv1):
https://verses.quran.foundation/fonts/quran/hafs/v4/colrv1/woff2/p{PAGE}.woff2
Font URL Pattern (OT-SVG for Firefox dark mode):
https://verses.quran.foundation/fonts/quran/hafs/v4/ot-svg/dark/woff2/p{PAGE}.woff2
API Request:
curl -H "x-auth-token: TOKEN" \
"https://apis.quran.foundation/content/api/v4/verses/by_page/1?mushaf=19&words=true&word_fields=code_v2,text_qpc_hafs"
| Feature | Madinah V2 (QCF V2) | King Fahd (KFGQPC) | Tajweed (QCF V4) |
|---|---|---|---|
| Mushaf ID | 1 | 5 | 19 |
| Font Type | Glyph-based | Unicode | Glyph-based + Color |
| Font Files | 604 (one per page) | 1 (single file) | 604 (one per page) |
| Quality | ⭐⭐⭐⭐⭐ Excellent | ⭐⭐⭐ Good | ⭐⭐⭐⭐⭐ Excellent |
| File Size | ~25MB (pages) | ~15MB (pages) | ~25MB (pages) |
| Font Size | ~25MB | ~500KB | ~30MB |
| Rendering | Pixel-perfect | Standard Unicode | Pixel-perfect + Colors |
| Maintenance | ✅ Active | ⚠️ Legacy | ✅ Active |
| Complexity | High | Low | High |
| Use Case | Production apps | Simple/prototype | Educational apps |
| Recommended | ✅ YES | ❌ No | ⚠️ Only for Tajweed |
QCF V2 & V4 (Glyph-based):
// Each word uses a special glyph code
{
"code_v2": "ﱁ", // Special glyph
"page_number": 1,
"text_qpc_hafs": "بِسۡمِ" // Fallback
}
// Must use innerHTML (not textContent)
span.innerHTML = word.code_v2;
span.style.fontFamily = `p${word.pageNumber}-v2`;
KFGQPC (Unicode):
// Standard Unicode text
{
"text_qpc_hafs": "بِسۡمِ"
}
// Can use textContent
span.textContent = word.text_qpc_hafs;
span.style.fontFamily = 'UthmanicHafs';
QCF V2 & V4:
// Dynamic per-page loading
async function loadPageFont(pageNumber: number, version: 'v2' | 'v4' = 'v2') {
const fontUrl = `https://verses.quran.foundation/fonts/quran/hafs/${version}/woff2/p${pageNumber}.woff2`;
const fontFace = new FontFace(
`p${pageNumber}-${version}`,
`url('${fontUrl}')`
);
await fontFace.load();
document.fonts.add(fontFace);
}
KFGQPC:
/* Single font for everything */
@font-face {
font-family: 'UthmanicHafs';
src: url('https://verses.quran.foundation/fonts/quran/hafs/uthmanic_hafs/UthmanicHafs1Ver18.woff2');
}
✅ Default choice for most apps
When:
Trade-offs:
⚠️ Only for quick prototypes or simple use cases
When:
Trade-offs:
🎨 Only when you specifically need Tajweed colors
When:
Trade-offs:
// ✅ Recommended
const MUSHAF_ID = 1; // QCF V2
const WORD_FIELDS = 'code_v2,text_qpc_hafs,line_number,page_number,position';
Migration Path:
KFGQPC (ID: 5)
↓
1. Update mushaf parameter to 1
2. Change word_fields to include code_v2
3. Implement per-page font loading
4. Use innerHTML for code_v2 rendering
5. Add fallback to text_qpc_hafs
↓
QCF V2 (ID: 1) ✅
Two-Mushaf Strategy:
const mushafs = {
standard: 1, // QCF V2 (default)
tajweed: 19 // QCF V4 (optional)
};
// Let user toggle between them
function switchMushaf(enableTajweed: boolean) {
return enableTajweed ? mushafs.tajweed : mushafs.standard;
}
Use Mushaf Madinah V2 (QCF V2) - ID: 1
Reasons:
Add Tajweed (QCF V4) - ID: 19 only if:
King Fahd (KFGQPC) - ID: 5 because:
// src/core/types.ts
export type MushafLayout =
| 'hafs-v2' // QCF V2 - RECOMMENDED
| 'hafs-v4'; // Tajweed - OPTIONAL
export const DEFAULT_MUSHAF: MushafLayout = 'hafs-v2';
export const MUSHAF_CONFIGS = {
'hafs-v2': {
id: 1,
name: 'Medina Mushaf (QCF V2)',
wordFields: 'code_v2,text_qpc_hafs,line_number,page_number',
fontType: 'glyph' as const,
totalPages: 604,
},
'hafs-v4': {
id: 19,
name: 'Medina Mushaf with Tajweed',
wordFields: 'code_v2,text_qpc_hafs,line_number,page_number',
fontType: 'glyph' as const,
totalPages: 604,
},
} as const;
Bottom Line: Always use Mushaf Madinah V2 (QCF V2, ID: 1) unless you have a specific reason to use Tajweed colors, in which case add QCF V4 (ID: 19) as an optional feature.