An embeddable widget that calculates and displays reading time for any webpage
npm install @suniltaneja/reading-time-widgetA lightweight, embeddable web component that calculates and displays reading time for any webpage content. Zero dependencies, fully isolated with Shadow DOM.
- 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
``html`
`bash`
npm install @suniltaneja/reading-time-widget
`javascript`
import '@suniltaneja/reading-time-widget';
Add the widget anywhere in your HTML:
`html`
That's it! The widget will automatically find your page content and display reading statistics.
Customize the widget using HTML attributes:
`html`
wpm="200"
position="floating"
selector=".blog-post"
closable="true">
| 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 |
- 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
`html`
`html`
`html`
`html`
`html`
`html`
`html`
wpm="200"
position="fixed-bottom"
selector="article">
`javascript
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'));
`
1. Content Detection - Finds content using smart CSS selectors, prioritizing semantic elements like and
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
Works in all modern browsers that support Web Components:
- Chrome 54+
- Firefox 63+
- Safari 10.1+
- Edge 79+
- Bun runtime
`bash`
git clone https://github.com/yourusername/reading-time-widget.git
cd reading-time-widget
bun install
`bashStart development server
bun run dev
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
(for example: v1.0.1).$3
- 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$3
1. Update the version in
(example: 1.0.1) and commit.
2. Create and push a git tag:`bash
git tag v1.0.1
git push origin v1.0.1
`Pushing the tag triggers the workflow in
, which builds dist/ and runs npm publish --access public.$3
The build generates three files in
dist/:-
reading-time-widget.min.js - IIFE bundle for