Reading Time Widget

A lightweight, embeddable web component that calculates and displays reading time for any webpage content. Zero dependencies, fully isolated with Shadow DOM.

Features

• Zero dependencies - Pure vanilla JavaScript
• Shadow DOM isolation - Styles won't conflict with your page
• Smart content detection - Automatically finds article content
• Multiple themes - Light and dark modes
• Flexible positioning - Inline, fixed, or floating/draggable
• Mobile friendly - Touch support and responsive design
• Persistent state - Remembers position and visibility

Installation

Via Script Tag

<script src="https://unpkg.com/@suniltaneja/reading-time-widget/dist/reading-time-widget.min.js"></script>

Via NPM

npm install @suniltaneja/reading-time-widget

import '@suniltaneja/reading-time-widget';

Usage

Add the widget anywhere in your HTML:

<reading-time-widget></reading-time-widget>

That's it! The widget will automatically find your page content and display reading statistics.

Configuration

Customize the widget using HTML attributes:

<reading-time-widget
  theme="dark"
  wpm="200"
  position="floating"
  selector=".blog-post"
  closable="true">
</reading-time-widget>

Attributes

| Attribute | Default | Description | |-----------|---------|-------------| | selector | article, main, .content, .post, .entry-content, [role="main"], body | CSS selector for content to analyze | | wpm | 230 | Words per minute reading speed | | theme | light | Color theme: light or dark | | position | inline | Widget position: inline, fixed-top, fixed-bottom, or floating | | closable | false (true for floating) | Show close button |

Position Options

• inline - Embeds within page flow (default)
• fixed-top - Fixed header bar at top of viewport
• fixed-bottom - Fixed footer bar at bottom of viewport
• floating - Draggable widget, position saved to localStorage

Examples

Basic Usage

<reading-time-widget></reading-time-widget>

Dark Theme

<reading-time-widget theme="dark"></reading-time-widget>

Custom Reading Speed

<reading-time-widget wpm="180"></reading-time-widget>

Fixed Position

<reading-time-widget position="fixed-top"></reading-time-widget>

Floating Draggable Widget

<reading-time-widget position="floating"></reading-time-widget>

Target Specific Content

<reading-time-widget selector="#my-article"></reading-time-widget>

Combine Options

<reading-time-widget
  theme="dark"
  wpm="200"
  position="fixed-bottom"
  selector="article">
</reading-time-widget>

JavaScript API

const widget = document.querySelector('reading-time-widget');

// Show/hide programmatically
widget.show();
widget.hide();

// Listen to events
widget.addEventListener('close', () => console.log('Widget closed'));
widget.addEventListener('open', () => console.log('Widget opened'));

How It Works

1. Content Detection - Finds content using smart CSS selectors, prioritizing semantic elements like <article> and <main>
2. Text Extraction - Clones content and removes non-text elements (scripts, nav, ads, etc.)
3. Calculation - Counts words and calculates reading time based on WPM setting
4. Display - Shows time (e.g., "5 min read"), word count, and character count

Browser Support

Works in all modern browsers that support Web Components:

• Chrome 54+
• Firefox 63+
• Safari 10.1+
• Edge 79+

Development

Prerequisites

• Bun runtime

Setup

git clone https://github.com/yourusername/reading-time-widget.git
cd reading-time-widget
bun install

Commands

# Start development server
bun run dev

# Build for production
bun run build

# Clean dist folder
bun run clean

Release (Tag + Auto Publish)

This repo includes a GitHub Actions workflow that publishes the package to npm when you push a version tag that starts with v (for example: v1.0.1).

Prerequisites

• Add a repository secret named NPM_TOKEN in GitHub:
  • GitHub: Settings -> Secrets and variables -> Actions -> New repository secret
  • npm: create an Automation access token with publish permissions for @suniltaneja

Create a release tag

1. Update the version in package.json (example: 1.0.1) and commit.
2. Create and push a git tag:

git tag v1.0.1
git push origin v1.0.1

Pushing the tag triggers the workflow in .github/workflows/publish.yml, which builds dist/ and runs npm publish --access public.

Output

The build generates three files in dist/:

• reading-time-widget.min.js - IIFE bundle for <script> tags
• reading-time-widget.esm.js - ES module for imports
• reading-time-widget.d.ts - TypeScript declarations

License

MIT