Indice di lettura con progress bar

Un pattern pensato per guide e documentazione: mostra quanto manca alla fine, evidenzia la sezione corrente e offre un ritorno rapido all'inizio del contenuto.

Codice nella Snippet Library Tutti i componenti

Capitolo 1

Contesto

In una guida lunga l'utente deve capire dove si trova senza perdere il filo. Un indice laterale aiuta a orientarsi e riduce il bisogno di tornare continuamente in cima.

La barra di avanzamento non sostituisce i titoli, ma aggiunge un feedback immediato sulla distanza dalla fine.

Capitolo 2

Setup

Il markup separa indice, contenuto e progress bar. Il JavaScript legge le sezioni disponibili e mantiene sincronizzati link attivo e percentuale di scroll.

Su pagine reali puoi collegarlo al documento intero oppure a un contenitore scrollabile, come in questa demo.

Capitolo 3

Controlli

Il componente deve restare leggibile, non coprire contenuti e funzionare anche senza animazioni complesse. I link dell'indice usano anchor normali e restano comprensibili.

Il pulsante torna su e utile quando il contenuto e molto lungo o quando l'indice diventa sticky nella pagina finale.

Capitolo 4

Prossimi passi

Puoi aggiungere sottosezioni, contatori, stato completato o integrazione con il layout delle guide Codedge. La base rimane piccola e facile da mantenere.

Il punto non e decorare lo scroll: e dare orientamento a chi legge.

Quando usarlo

Per guide lunghe, documentazione, changelog articolati e pagine tutorial con molte sezioni.

Cosa risolve

Rende visibili posizione, avanzamento e ritorno rapido senza affidarsi a un semplice bottone fisso.

Come adattarlo

Usalo con il documento intero o con un contenitore scrollabile. Puoi rendere sticky l'indice su desktop.

Migliorare l'UX di guide e articoli lunghi con Indice di Lettura e Progress Bar

Quando gli utenti leggono articoli lunghi, documentazioni tecniche o guide dettagliate, possono facilmente perdere l'orientamento o sottostimare lo sforzo richiesto per completare la lettura. Un indice di lettura interattivo (Table of Contents o TOC) abbinato a una barra di avanzamento visiva (scroll progress bar) migliora sensibilmente l'esperienza utente (UX), incentivando il completamento della lettura e offrendo punti di ancoraggio rapidi per saltare da una sezione all'altra.

Questo componente propone un layout diviso: un pannello laterale che funge da indice e un contenitore principale per il testo. Tramite l'uso di JavaScript e dell'API Intersection Observer (o del monitoraggio dell'evento scroll), lo script rileva quale sezione è visibile nello schermo e applica una classe di stato (come is-active) al link corrispondente nell'indice. Contemporaneamente, la barra di progresso orizzontale in alto si riempie in base alla percentuale di scorrimento del testo all'interno del contenitore.

Dal punto di vista dell'accessibilità, l'indice laterale è racchiuso all'interno di un tag <aside> con una label descrittiva aria-label="Indice della guida", permettendo agli screen reader di identificarlo come area di navigazione rapida. I link dell'indice puntano alle ancore interne dei titoli delle sezioni tramite ID univoci. Viene inoltre incluso un pulsante "Torna su" accessibile, che permette di riposizionare rapidamente la visualizzazione all'inizio del documento, ideale per evitare lunghi scorrimenti manuali specialmente su dispositivi mobili.

FAQ rapide sull'indice di lettura

Come viene calcolata la percentuale della barra di scorrimento?

JavaScript calcola il rapporto tra lo spazio di scorrimento già effettuato (scrollTop) e lo spazio totale scollabile (scrollHeight - clientHeight) del contenitore di scorrimento, convertendolo in una percentuale che aggiorna dinamicamente la larghezza inline della barra di progresso.

Intersection Observer è migliore rispetto all'evento scroll per rilevare la sezione attiva?

Sì, Intersection Observer è molto più performante poiché non sovraccarica il thread principale con continui calcoli matematici ad ogni singolo pixel di scorrimento. Lo script si attiva solo quando le sezioni predefinite entrano o escono dalla viewport secondo soglie stabilite.

Come funziona il pulsante 'Torna su' per l'accessibilità?

Il pulsante effettua uno scroll fluido verso l'alto tramite JavaScript e, molto importante, ripristina il focus logico all'inizio del documento o sul contenitore principale per consentire all'utente da tastiera o screen reader di riprendere immediatamente la navigazione.