Text versus visual representation
You can show a reader the Qur’an as a string set in a font, or as the printed page of a specific muṣḥaf drawn as vectors. They look similar on screen and they are different products with different data, different weights and different failure modes. Most apps need both. This page is about choosing which one answers which question.
For most readers the Qur’an is a particular printed page: the same line breaks, the same page ends, the same ornaments they memorised from. A string in a font gives them the same words in a layout they have never seen. That is fine for search results, translations and study tools, and wrong for a memorisation app, where "the ayah at the bottom of the left page" is how people remember.
The choice is: does the reader need the words, or the page?
The two representations, side by side
| Text | Visual | |
|---|---|---|
| What you receive | Unicode strings, one per word, in seven readings | Glyph outlines of one printed page, plus a layer that says which ink is which verse or word |
| From | Quran Text | Quran SVG, Quran SVG Elements, Quran Engine |
| Layout | yours — the browser or platform lays it out | the publisher's, exactly: line breaks, page breaks, ornaments |
| Needs a font | yes, and a specific one per edition | no — the ink is in the file |
| Selectable, find-in-page, copy | yes | no — there is no <text> element in any page |
| Smallest addressable thing | a character | an ayah (SVG), a word or a mark (Elements, Engine) |
| Smallest download for one ayah | the whole edition: 1.9–3.1 MB | one page: page 1 of Ḥafṣ is 196 KB raw, 33 KB Brotli |
| Riwayat available | all seven | five (SVG); one, Ḥafṣ (Elements, Engine) |
| Fails silently when | the font is missing — words render blank | you assume the file knows what an ayah says |
Warsh, Qālūn and al-Sūsī use Arabic Extended-B code points that Unicode only added in 2021, and almost no general
font draws them. text.length is right, a code-point dump is right, and the screen shows empty boxes or blank
space. Every muṣḥaf file in Quran Text names the font its text is set in; ship that one — seven fonts, one per
edition, not one for all seven.
Quran SVG's pages carry no text at all: a tap resolves to a surah and ayah attribute on a polygon, and that is
everything the file knows. Elements goes further, every word group carries its printed form as
data-rasm-uthmani, but there is still nothing to search, select or copy. If your feature needs the words,
join to Quran Text by word key. Nothing throws if you forget; you have a page
you can tap but cannot read from.
Choosing
| The reader wants to | Use | Because |
|---|---|---|
| Read or memorise from the page they know | visual | the layout is the content for them |
| See search results, a translation beside the text, a quoted ayah | text | you control layout and the string is selectable |
| Tap a verse on the page and see its translation | visual + text | polygon → reference → Quran Text |
| Tap a word, colour a word, follow a recitation word by word | Elements or Engine, + text | those are the only visual formats that address a word |
| Colour tajwīd on a string | text + Quran Tajweed | spans are character offsets into a text |
| Colour tajwīd on the printed page | Elements + Tajweed | a mark is its own path, so a rule can address it |
| Show any reading other than Ḥafṣ with word-level interaction | nothing today | only the Ḥafṣ muṣḥaf has been split — see Riwayat |
| Render pages on a phone | Engine | SVG of a full page's density does not perform on mobile |
The three visual blocks are not a queue. Coverage narrows as addressing deepens: Quran SVG covers every vectorised muṣḥaf and addresses an ayah; Elements covers only what has been split and addresses a word or a mark; Engine draws the split muṣḥafs on mobile. Elements ships 604 whole pages too; the difference is what you can address once a page is on screen, never "pages versus parts".
What the two do not share
They are built from the same publisher, and they still do not share coordinates, offsets or strings.
- A text position is not a page position. Quran Text knows which page a word is on (
page_starts), not where on it. Only the visual blocks carry geometry, and it belongs to one page of one muṣḥaf — see Page geometry. - A tajwīd span is not a mark on the page. A span is a character range into one text; a mark is a path with a name. Colouring the page from spans means translating through the word key and then the mark taxonomy, not applying offsets to outlines.
- The printed form on an Elements word and the Quran Text word are the same publisher's spelling — and can still differ in bytes, for the reasons in Encoding. Join on the key.
Decide per feature, not per app
A study app's reading view is visual; its search is text; its share-as-image is a visual crop. Write the decision down for each screen.
Load the visual page, resolve taps to a reference
root.querySelectorAll<SVGPathElement>(".ayahPolygon").forEach((p) => { p.addEventListener("click", () => { open(Number(p.getAttribute("surah")), Number(p.getAttribute("ayah"))); }); });This is the Quran SVG integration the demo on this site runs, trimmed. The reference is all the page gives you.
Fetch the words for that reference from the text dataset
const m = await Mushaf.hafs(); m.ayah(surah, ayah).text;The muṣḥaf you loaded for the page and the edition you loaded for the text must be the same reading, or the ayah numbers will not line up. Persist both keys.
How this data is made
The text is extracted unedited from the publisher's digital packages, one per reading, and each file names its package and digest. The pages are vectorised from the publisher's printed edition; Quran SVG derives its ayah polygons from each page's own ayah medallions, and Elements regroups that ink into words and named marks without moving or redrawing a path.