ReadTime

A lightweight, performance-focused, attribute-driven JavaScript library to calculate and render reading time directly in the DOM.

Inspired by declarative attribute systems, ReadTime allows you to define reading time behavior using simple HTML attributes — no configuration objects, no framework dependencies.

Zero dependencies. Minimal footprint. Production-ready.

Installation

CDN (Recommended)

<!-- Readtime Library -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/readtime.min.js"></script>

Use defer to prevent render blocking.

How It Works

ReadTime operates in two modes:

1. Container Mode — Context defined by DOM hierarchy.
2. Context Mode — Context defined manually via shared key.

Container Mode

Creates an internal relationship between content and time elements using DOM hierarchy.

Basic Example

<div data-readtime="container">
  <article data-readtime="content">
    <p>Your article content here...</p>
  </article>

  <span data-readtime="time"></span>
</div>

Behavior

• All data-readtime="content" elements inside the container are summed.
• Only the first data-readtime="time" inside the container is updated.
• Default WPM: 200.
• If total words = 0 → result = 0.

Multiple Content Blocks

<div data-readtime="container">
  <section data-readtime="content">Intro text...</section>
  <section data-readtime="content">Main content...</section>

  <span data-readtime="time"></span>
</div>

All content blocks are summed.

Custom WPM

<div data-readtime="container">
  <article data-readtime="content" data-readtime-wpm="180">
    Technical content...
  </article>

  <span data-readtime="time"></span>
</div>

Rule

If multiple content elements exist, the lowest WPM found is used (conservative calculation).

Ignoring Content

<article data-readtime="content">
  <p>Main text...</p>

  <div data-readtime-ignore>
    <p>This block is ignored.</p>
  </div>
</article>

Any descendant with data-readtime-ignore is completely excluded from word counting.

Context Mode

Allows linking content and time elements outside a container using a shared key.

Basic Example

<span data-readtime="time" data-readtime-context="post-1"></span>

<article data-readtime="content" data-readtime-context="post-1">
  Content here...
</article>

Behavior

• All content elements with the same data-readtime-context value are summed.
• All matching time elements are updated.
• Context value must be a literal string (not a selector).

Multiple Contents + Multiple Times

<span data-readtime="time" data-readtime-context="article-A"></span>
<span data-readtime="time" data-readtime-context="article-A"></span>

<section data-readtime="content" data-readtime-context="article-A">
  Section 1...
</section>

<section data-readtime="content" data-readtime-context="article-A">
  Section 2...
</section>

All content sections are summed.
All time elements are updated.

Attribute Reference

| Attribute | Applies To | Required | Description | |------------|------------|----------|-------------| | data-readtime="container" | Any element | Optional | Defines DOM-scoped context | | data-readtime="content" | Any element | Required (per group) | Source text for calculation | | data-readtime="time" | Any element | Required (per group) | Where result is injected | | data-readtime-context="NAME" | content + time | Optional | Manual context binding (outside container) | | data-readtime-wpm="number" | content | Optional | Words per minute override | | data-readtime-ignore | Descendants of content | Optional | Excludes subtree from count |

Calculation Rules

| Rule | Behavior | |------|----------| | Default WPM | 200 | | Multiple WPMs | Uses lowest value | | Words = 0 | Result = 0 | | Container mode | Updates only first time | | Context mode | Updates all matching time elements | | Ignore blocks | Entire subtree removed |

Public API

ReadTime exposes a minimal API for dynamic environments.

Recalculate manually

ReadTime.refresh();

Use after:

• CMS injection
• Tab switches
• Lazy-loaded content
• Dynamic rendering

Enable Mutation Observer

ReadTime.observe();

Automatically recalculates when DOM changes.

Disable:

ReadTime.disconnect();

Performance Notes

ReadTime is designed to:

• Avoid global namespace pollution
• Work with deferred loading
• Minimize DOM reads
• Avoid layout thrashing
• Keep observers opt-in only

Best practices:

• Always use defer
• Avoid enabling observer unless necessary
• Prefer Container Mode when possible

Browser Support

Modern browsers (ES2018+).

Versioning

Follows Semantic Versioning:

MAJOR.MINOR.PATCH

Example:

v0.1.0

License

MIT