# ScrollTOC A lightweight, customizable table of contents navigation component that tracks reading progress through your content. ## Features - **Auto-extraction** — Automatically finds headers in your content - **Progress tracking** — Real-time progress indicator between sections (0-1) - **Scroll-aware fade** — Fades to transparent while scrolling, returns on stop - **Click navigation** — Smooth scroll to any section - **Fully customizable** — Colors, typography, positioning, animations - **Multiple styles** — Bar, dot, or line progress indicators - **Callbacks** — Hook into header changes and progress updates - **Zero dependencies** — Pure vanilla JavaScript - **Responsive** — Auto-hides on smaller screens ## Installation ### Via Script Tag ```html ``` ### Via npm (coming soon) ```bash npm install scroll-toc ``` ## Quick Start ```html

Introduction

Content here...

Getting Started

More content...

``` That's it! ScrollTOC will automatically find all headers and create a floating navigation. ## Configuration Pass an options object to customize behavior: ```javascript const toc = new ScrollTOC({ // All options with defaults shown contentSelector: '.content', headerLevels: ['h1', 'h2', 'h3', 'h4'], position: 'right', // ... see full options below }); ``` ### All Options #### Content & Structure | Option | Type | Default | Description | |--------|------|---------|-------------| | `contentSelector` | `string` | `'.content'` | CSS selector for the content container | | `headerLevels` | `array` | `['h1','h2','h3','h4']` | Header tags to include | | `showNumbers` | `boolean` | `false` | Show section numbers | | `indent` | `boolean` | `true` | Indent nested headers | | `indentSize` | `string` | `'0.75rem'` | Indentation amount per level | #### Positioning | Option | Type | Default | Description | |--------|------|---------|-------------| | `position` | `string` | `'right'` | `'left'` or `'right'` | | `offsetX` | `string` | `'2rem'` | Horizontal offset from edge | | `offsetY` | `string` | `'50%'` | Vertical position | | `width` | `string` | `'220px'` | Component width | | `maxHeight` | `string` | `'60vh'` | Maximum height (scrollable) | #### Typography | Option | Type | Default | Description | |--------|------|---------|-------------| | `fontFamily` | `string` | `'inherit'` | Font family | | `fontSize` | `object` | `{h1:'0.9rem',...}` | Font size per header level | | `fontWeight` | `object` | `{normal:'400',active:'600'}` | Font weights | ```javascript // Example: Custom typography fontSize: { h1: '1rem', h2: '0.9rem', h3: '0.85rem', h4: '0.8rem' }, fontWeight: { normal: '400', active: '700' } ``` #### Colors | Option | Type | Default | Description | |--------|------|---------|-------------| | `colors.text` | `string` | `'rgba(60,60,60,0.7)'` | Default text color | | `colors.textActive` | `string` | `'rgba(20,20,20,1)'` | Active section text | | `colors.progressBar` | `string` | `'rgba(0,0,0,0.8)'` | Progress indicator fill | | `colors.progressTrack` | `string` | `'rgba(0,0,0,0.08)'` | Progress indicator track | | `colors.background` | `string` | `'rgba(255,255,255,0.85)'` | Component background | | `colors.border` | `string` | `'rgba(0,0,0,0.06)'` | Border color | ```javascript // Example: Custom color scheme colors: { text: 'rgba(100, 100, 100, 0.6)', textActive: '#e63946', progressBar: '#e63946', progressTrack: 'rgba(230, 57, 70, 0.15)', background: 'rgba(255, 255, 255, 0.95)', border: 'rgba(0, 0, 0, 0.05)' } ``` #### Scroll Fade Effect | Option | Type | Default | Description | |--------|------|---------|-------------| | `fadeOnScroll` | `boolean` | `true` | Enable fade while scrolling | | `fadeOpacity.min` | `number` | `0.3` | Opacity while scrolling | | `fadeOpacity.max` | `number` | `1` | Opacity when idle | | `fadeDelay` | `number` | `150` | Ms before fading back in | ```javascript // Example: Subtle fade fadeOnScroll: true, fadeOpacity: { min: 0.2, max: 1 }, fadeDelay: 300 ``` #### Progress Indicator | Option | Type | Default | Description | |--------|------|---------|-------------| | `progressStyle` | `string` | `'bar'` | `'bar'`, `'dot'`, or `'line'` | **Styles:** - `'bar'` — Vertical bar that fills based on progress - `'dot'` — Circle that fills when section is active - `'line'` — Vertical line showing overall progress #### Animation & Scrolling | Option | Type | Default | Description | |--------|------|---------|-------------| | `scrollBehavior` | `string` | `'smooth'` | `'smooth'` or `'auto'` | | `scrollOffset` | `number` | `80` | Pixels from top when navigating | | `transitionDuration` | `string` | `'0.3s'` | CSS transition duration | | `transitionEasing` | `string` | `'cubic-bezier(...)'` | CSS easing function | #### Callbacks | Option | Type | Default | Description | |--------|------|---------|-------------| | `onInit` | `function` | `null` | Called after initialization | | `onHeaderChange` | `function` | `null` | Called when active section changes | | `onProgressChange` | `function` | `null` | Called on scroll progress update | ```javascript // Example: Using callbacks onInit: (instance) => { console.log(`Found ${instance.headers.length} headers`); }, onHeaderChange: (index, header, instance) => { console.log(`Now reading: ${header.text}`); // Update page title, analytics, etc. }, onProgressChange: (progress, index, instance) => { // progress is 0-1 between current and next header console.log(`${Math.round(progress * 100)}% through section`); } ``` #### Advanced | Option | Type | Default | Description | |--------|------|---------|-------------| | `classPrefix` | `string` | `'stoc'` | CSS class prefix for styling | ## API Methods ### `getCurrentHeader()` Returns the currently active header object. ```javascript const current = toc.getCurrentHeader(); console.log(current.text); // "Getting Started" console.log(current.level); // "h2" console.log(current.id); // "getting-started" ``` ### `getProgress()` Returns the current progress (0-1) between the active header and the next. ```javascript const progress = toc.getProgress(); console.log(`${Math.round(progress * 100)}% complete`); ``` ### `getAllHeaders()` Returns an array of all tracked header objects. ```javascript const headers = toc.getAllHeaders(); headers.forEach((h, i) => { console.log(`${i + 1}. ${h.text} (${h.level})`); }); ``` ### `scrollTo(index)` Programmatically scroll to a section by index. ```javascript toc.scrollTo(0); // Scroll to first header toc.scrollTo(3); // Scroll to fourth header ``` ### `show()` / `hide()` Toggle visibility of the navigation. ```javascript toc.hide(); // Hide the TOC toc.show(); // Show the TOC ``` ### `destroy()` Remove the TOC from the DOM and clean up styles. ```javascript toc.destroy(); ``` ### `refresh()` Re-scan content and rebuild the TOC (useful after dynamic content changes). ```javascript // After adding new content dynamically document.querySelector('.content').innerHTML += '

New Section

...

'; toc.refresh(); ``` ## Examples ### Minimal Setup ```javascript new ScrollTOC(); ``` ### Blog Style (Right Side) ```javascript new ScrollTOC({ contentSelector: 'article', headerLevels: ['h1', 'h2', 'h3'], position: 'right', offsetX: '2rem', colors: { textActive: '#d63384', progressBar: '#d63384' } }); ``` ### Documentation Style (Left Side) ```javascript new ScrollTOC({ contentSelector: '.docs-content', headerLevels: ['h2', 'h3', 'h4'], position: 'left', offsetX: '1.5rem', offsetY: '120px', width: '260px', showNumbers: true, progressStyle: 'dot', fadeOnScroll: false }); ``` ### Dark Theme ```javascript new ScrollTOC({ contentSelector: '.content', colors: { text: 'rgba(255, 255, 255, 0.5)', textActive: '#60a5fa', progressBar: '#60a5fa', progressTrack: 'rgba(96, 165, 250, 0.2)', background: 'rgba(30, 30, 30, 0.9)', border: 'rgba(255, 255, 255, 0.1)' } }); ``` ### With Analytics Integration ```javascript new ScrollTOC({ contentSelector: '.article', onHeaderChange: (index, header) => { // Track section views analytics.track('Section Viewed', { section: header.text, index: index }); }, onProgressChange: (progress, index, instance) => { // Track read completion if (progress > 0.9 && index === instance.headers.length - 1) { analytics.track('Article Completed'); } } }); ``` ## Styling Override You can override styles using the class prefix (default: `stoc`): ```css /* Custom styling */ .stoc-nav { /* Container positioning overrides */ } .stoc-inner { /* Card styling */ border-radius: 0; box-shadow: none; } .stoc-title { /* "Contents" header */ display: none; /* Hide title */ } .stoc-link { /* Individual links */ } .stoc-link.stoc-active { /* Active link state */ } .stoc-progress-fill { /* Progress bar fill */ } ``` ## Browser Support - Chrome 60+ - Firefox 55+ - Safari 12+ - Edge 79+ ## Responsive Behavior By default, ScrollTOC hides on screens narrower than 1200px. Override with CSS: ```css @media (max-width: 1400px) { .stoc-nav { display: none; } } /* Or show on mobile with different positioning */ @media (max-width: 768px) { .stoc-nav { position: fixed; bottom: 0; left: 0; right: 0; top: auto; transform: none; width: 100%; } } ``` ## License MIT © 2026

Your Cart

Code Repository

All Code

Telemetry

Security

JWT Identity

FileService

scroll-toc

Tailwind.NET

Your Cart