DEV Community

Cover image for Every Readability Formula Explained (with JavaScript Examples)
ckmtools
ckmtools

Posted on

Every Readability Formula Explained (with JavaScript Examples)

#node #typescript #javascript #webdev

Readability formulas have been around since the 1940s. The U.S. military commissioned the first one to make training manuals less confusing. Newspapers adopted them to keep articles accessible. Today, content teams at organizations like gov.uk and the NYT use them to measure whether their writing actually reaches people.

But if you search for "readability formulas javascript," you get scattered npm packages — each implementing one formula — and blog posts from 2018. No single guide covers all the formulas with working code you can install and run.

This article covers all 8 major readability formulas, explains the math behind each one, and shows how to compute them in JavaScript with textlens.

Setup 

npm install textlens
Enter fullscreen mode Exit fullscreen mode

textlens is a zero-dependency TypeScript toolkit. It works in Node.js 16+ and ships ESM and CommonJS with full type definitions.

const { readability, statistics } = require('textlens');
// or: import { readability, statistics } from 'textlens';
Enter fullscreen mode Exit fullscreen mode

Every example below uses the same sample text:

const text = `The quick brown fox jumps over the lazy dog.
This sentence contains several common English words.
Reading difficulty depends on word length and sentence structure.
Shorter sentences with familiar words score as more readable.`;
Enter fullscreen mode Exit fullscreen mode

The 8 Readability Formulas

1. Flesch Reading Ease

The most widely known formula. Created by Rudolf Flesch in 1948. Returns a score from 0 to 100 — higher means easier to read.

The math:

score = 206.835 - 1.015 × (words / sentences) - 84.6 × (syllables / words)
Enter fullscreen mode Exit fullscreen mode

Two factors drive the score: average sentence length and average syllables per word. Short sentences with short words score high. Academic prose with long sentences and polysyllabic words scores low.

Score interpretation:

Score Difficulty Example
90-100 Very easy Children's books
60-70 Standard Newspaper articles
30-50 Difficult Academic papers
0-30 Very difficult Legal documents

With textlens:

const scores = readability(text);
console.log(scores.fleschReadingEase.score);
// 72.4
console.log(scores.fleschReadingEase.interpretation);
// "Fairly easy to read"
Enter fullscreen mode Exit fullscreen mode

2. Flesch-Kincaid Grade Level

Same inputs as Flesch Reading Ease, but the coefficients are rearranged to output a U.S. grade level instead of a 0-100 score. Created by J. Peter Kincaid for the U.S. Navy in 1975.

The math:

grade = 0.39 × (words / sentences) + 11.8 × (syllables / words) - 15.59
Enter fullscreen mode Exit fullscreen mode

A result of 8.0 means an eighth grader can understand the text. Most successful blog posts land between grades 6 and 9.

console.log(scores.fleschKincaidGrade.grade);
// 5.6
console.log(scores.fleschKincaidGrade.interpretation);
// "6th grade"
Enter fullscreen mode Exit fullscreen mode

3. Gunning Fog Index

Created by Robert Gunning, a newspaper consultant, in 1952. The Fog Index specifically penalizes "complex words" — words with 3 or more syllables. This makes it stricter than Flesch-Kincaid for jargon-heavy text.

The math:

grade = 0.4 × ((words / sentences) + 100 × (complex_words / words))
Enter fullscreen mode Exit fullscreen mode

Where complex_words = words with 3+ syllables (excluding proper nouns, common suffixes, and compound words).

console.log(scores.gunningFogIndex.grade);
// 8.1
console.log(scores.gunningFogIndex.interpretation);
// "8th grade"
Enter fullscreen mode Exit fullscreen mode

If your Fog Index is above 12, you're writing at a level that most readers will struggle with. Cut the jargon.

4. Coleman-Liau Index

Unlike the previous formulas, Coleman-Liau uses character count instead of syllable count. This matters because syllable counting is inherently imprecise (is "fire" one syllable or two?), while character counting is deterministic.

The math:

grade = 0.0588 × L - 0.296 × S - 15.8
Enter fullscreen mode Exit fullscreen mode

Where L = average number of letters per 100 words, S = average number of sentences per 100 words.

console.log(scores.colemanLiauIndex.grade);
// 7.8
Enter fullscreen mode Exit fullscreen mode

Coleman-Liau is a good choice when you need consistent, reproducible scores across different implementations.

5. SMOG Index

"Simple Measure of Gobbledygook." Created by G. Harry McLaughlin in 1969. SMOG focuses specifically on polysyllabic words (3+ syllables) and is considered one of the most accurate grade-level predictors.

The math:

grade = 1.0430 × √(polysyllabic_words × (30 / sentences)) + 3.1291
Enter fullscreen mode Exit fullscreen mode

SMOG requires at least 30 sentences for statistical validity. For shorter texts, most implementations (including textlens) use a normalized version.

console.log(scores.smogIndex.grade);
// 7.2
Enter fullscreen mode Exit fullscreen mode

6. Automated Readability Index (ARI)

Originally designed for real-time readability monitoring on typewriters. Uses characters per word and words per sentence — no syllable counting needed.

The math:

grade = 4.71 × (characters / words) + 0.5 × (words / sentences) - 21.43
Enter fullscreen mode Exit fullscreen mode

ARI tends to give slightly higher grade levels than other formulas because it counts characters rather than syllables. A word like "through" (7 characters, 1 syllable) gets penalized more by ARI than by Flesch.

console.log(scores.automatedReadabilityIndex.grade);
// 4.8
Enter fullscreen mode Exit fullscreen mode

7. Dale-Chall Readability Score

Takes a completely different approach. Instead of measuring word length or syllables, Dale-Chall compares your text against a list of 3,000 words that 80% of fourth graders can understand. Words not on the list are "difficult."

The math:

score = 0.1579 × (difficult_words / words × 100) + 0.0496 × (words / sentences)
if (difficult_words / words > 0.05) score += 3.6365
Enter fullscreen mode Exit fullscreen mode 
console.log(scores.daleChallScore.grade);
// 6.4
Enter fullscreen mode Exit fullscreen mode

Dale-Chall is especially useful for content aimed at general audiences. If more than 5% of your words aren't on the familiar-word list, the formula adds a penalty.

8. Linsear Write Formula

Developed for the U.S. Air Force to assess technical manual readability. Classifies words as "easy" (2 or fewer syllables) or "hard" (3+ syllables), then weights them differently.

The math:

raw = (easy_words × 1 + hard_words × 3) / sentences
grade = raw > 20 ? raw / 2 : (raw - 1) / 2
Enter fullscreen mode Exit fullscreen mode 
console.log(scores.linsearWriteFormula.grade);
// 5.5
Enter fullscreen mode Exit fullscreen mode

The Consensus Grade: One Number to Rule Them All

Each formula has biases. Flesch-Kincaid over-penalizes syllables. Coleman-Liau over-penalizes long words with few syllables. Dale-Chall depends on a static word list from the 1940s.

textlens computes all 8 formulas and averages the 7 grade-level results (excluding Flesch Reading Ease, which uses a different scale) into a single consensusGrade:

const scores = readability(text);

// Individual formulas
console.log(scores.fleschReadingEase.score);  // 0-100 scale
console.log(scores.fleschKincaidGrade.grade); // US grade level
console.log(scores.gunningFogIndex.grade);
console.log(scores.colemanLiauIndex.grade);
console.log(scores.smogIndex.grade);
console.log(scores.automatedReadabilityIndex.grade);
console.log(scores.daleChallScore.grade);
console.log(scores.linsearWriteFormula.grade);

// Weighted average of all grade-level formulas
console.log(scores.consensusGrade); // 6.5
Enter fullscreen mode Exit fullscreen mode

The consensus grade smooths out the biases of individual formulas. One number, backed by seven formulas.

What Grade Level Should You Target?

Content type Target grade Flesch Ease
Blog posts 6-8 60-70
Technical docs 8-12 40-60
API reference 10-14 30-50
Academic papers 14+ 0-30

The average American reads at an 8th-grade level. If your consensus grade is above 12, consider:

  • Splitting long sentences
  • Replacing multisyllabic words with shorter alternatives
  • Breaking complex ideas into multiple sentences

CLI: Quick Check Without Writing Code 

npx textlens article.md
Enter fullscreen mode Exit fullscreen mode

For JSON output you can pipe to other tools:

npx textlens article.md --json | jq '.readability.consensusGrade'
Enter fullscreen mode Exit fullscreen mode

For a specific formula:

npx textlens article.md --formula flesch-reading-ease
Enter fullscreen mode Exit fullscreen mode

Why One Package Instead of Eight

Before textlens, computing all these formulas meant installing separate packages: flesch, flesch-kincaid, gunning-fog, coleman-liau, automated-readability, smog-formula, dale-chall-formula. That's 7 dependencies for 7 formulas, each with different APIs and maintainers.

textlens gives you all 8 formulas in a single, zero-dependency package with a consistent API. One install, one import, one function call.

npm install textlens
Enter fullscreen mode Exit fullscreen mode

If you find it useful, a star on GitHub helps others discover it.

This is part of the textlens series — a set of tutorials on text analysis in JavaScript and TypeScript.

Top comments (0)