Un lightbox immagini WordPress JavaScript permette di aprire le foto in una galleria a schermo intero senza installare plugin aggiuntivi. La soluzione usa un blocco HTML personalizzato per la struttura, il CSS aggiuntivo per l’aspetto grafico e un file JavaScript per apertura, chiusura e navigazione tra le immagini. Il metodo è adatto a WordPress con tema classico o a blocchi, ma richiede l’accesso ai file del tema child oppure a una modalità sicura per caricare codice personalizzato. Il risultato resta leggero, responsive e compatibile con mouse, tastiera e dispositivi touch.

Come funziona il lightbox immagini WordPress JavaScript

Il lightbox è una finestra sovrapposta alla pagina che mostra un’immagine in formato ingrandito, lasciando il resto dello schermo oscurato. In questa implementazione, ogni immagine della galleria contiene gli attributi data-full e data-caption: il primo indica l’immagine da visualizzare, mentre il secondo contiene la descrizione mostrata sotto la foto.

La soluzione comprende questi elementi:

Un contenitore HTML con le miniature della galleria.
Un overlay nascosto con immagine principale, didascalia e pulsanti.
Regole CSS responsive per lo schermo intero.
JavaScript per apertura, chiusura, tasti freccia e tasto Esc.
Attributi ARIA e testo alternativi per migliorare l’accessibilità.

Il codice non dipende da jQuery e non richiede librerie esterne. Per evitare problemi con gli aggiornamenti di WordPress o del tema, è preferibile utilizzare un tema child e non modificare direttamente i file del tema principale.

Creare la galleria HTML in WordPress

Nel pannello di WordPress apri l’articolo o la pagina interessata e inserisci un blocco HTML personalizzato. Incolla la struttura seguente, sostituendo gli URL delle immagini con quelli presenti nella Libreria media di WordPress.

<div class="wp-lightbox-gallery" aria-label="Galleria fotografica">
<button
class="wp-lightbox-item"
type="button"
data-full="https://example.com/wp-content/uploads/foto-1-grande.jpg"
data-caption="Descrizione della prima immagine">
<img
src="https://example.com/wp-content/uploads/foto-1-miniatura.jpg"
alt="Descrizione della prima immagine"
loading="lazy">
</button>

<button
class="wp-lightbox-item"
type="button"
data-full="https://example.com/wp-content/uploads/foto-2-grande.jpg"
data-caption="Descrizione della seconda immagine">
<img
src="https://example.com/wp-content/uploads/foto-2-miniatura.jpg"
alt="Descrizione della seconda immagine"
loading="lazy">
</button>

<button
class="wp-lightbox-item"
type="button"
data-full="https://example.com/wp-content/uploads/foto-3-grande.jpg"
data-caption="Descrizione della terza immagine">
<img
src="https://example.com/wp-content/uploads/foto-3-miniatura.jpg"
alt="Descrizione della terza immagine"
loading="lazy">
</button>
</div>

<div
class="wp-lightbox-overlay"
role="dialog"
aria-modal="true"
aria-label="Immagine ingrandita"
hidden>
<button class="wp-lightbox-close" type="button" aria-label="Chiudi immagine">
×
</button>

<button class="wp-lightbox-prev" type="button" aria-label="Immagine precedente">
‹
</button>

<figure class="wp-lightbox-figure">
<img class="wp-lightbox-image" src="" alt="">
<figcaption class="wp-lightbox-caption"></figcaption>
</figure>

<button class="wp-lightbox-next" type="button" aria-label="Immagine successiva">
›
</button>
</div>

Il valore di src può puntare a una miniatura ottimizzata, mentre data-full dovrebbe contenere l’URL di una versione più grande. L’attributo alt deve descrivere il contenuto dell’immagine e non deve essere lasciato vuoto quando la foto trasmette informazioni.

Aggiungere lo stile CSS del lightbox

Il CSS può essere inserito in Aspetto > Personalizza > CSS aggiuntivo nei temi classici. Nei temi a blocchi il percorso può variare, ma l’area da cercare è l’editor degli stili globali o il campo CSS aggiuntivo previsto dal tema.

.wp-lightbox-gallery {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
gap: 16px;
margin: 24px 0;
}

.wp-lightbox-item {
display: block;
padding: 0;
border: 0;
background: transparent;
cursor: zoom-in;
overflow: hidden;
border-radius: 8px;
}

.wp-lightbox-item img {
display: block;
width: 100%;
aspect-ratio: 4 / 3;
object-fit: cover;
transition: transform 0.25s ease;
}

.wp-lightbox-item:hover img,
.wp-lightbox-item:focus-visible img {
transform: scale(1.04);
}

.wp-lightbox-overlay {
position: fixed;
inset: 0;
z-index: 99999;
display: flex;
align-items: center;
justify-content: center;
padding: 56px 72px;
background: rgb(0 0 0 / 90%);
}

.wp-lightbox-overlay[hidden] {
display: none;
}

.wp-lightbox-figure {
display: flex;
flex-direction: column;
align-items: center;
max-width: min(1100px, 90vw);
max-height: 90vh;
margin: 0;
}

.wp-lightbox-image {
display: block;
max-width: 100%;
max-height: 78vh;
width: auto;
height: auto;
object-fit: contain;
}

.wp-lightbox-caption {
max-width: 90vw;
margin-top: 14px;
color: #fff;
font-size: 1rem;
line-height: 1.5;
text-align: center;
}

.wp-lightbox-close,
.wp-lightbox-prev,
.wp-lightbox-next {
position: absolute;
border: 0;
color: #fff;
background: rgb(0 0 0 / 45%);
cursor: pointer;
line-height: 1;
}

.wp-lightbox-close {
top: 16px;
right: 22px;
padding: 4px 12px;
font-size: 2.4rem;
}

.wp-lightbox-prev,
.wp-lightbox-next {
top: 50%;
padding: 8px 16px;
transform: translateY(-50%);
font-size: 3rem;
}

.wp-lightbox-prev {
left: 18px;
}

.wp-lightbox-next {
right: 18px;
}

.wp-lightbox-close:focus-visible,
.wp-lightbox-prev:focus-visible,
.wp-lightbox-next:focus-visible,
.wp-lightbox-item:focus-visible {
outline: 3px solid #72d6ff;
outline-offset: 3px;
}

@media (max-width: 600px) {
.wp-lightbox-overlay {
padding: 48px 18px;
}

.wp-lightbox-prev,
.wp-lightbox-next {
padding: 6px 10px;
font-size: 2.2rem;
}

.wp-lightbox-prev {
left: 4px;
}

.wp-lightbox-next {
right: 4px;
}

.wp-lightbox-image {
max-height: 72vh;
}
}

position: fixed mantiene l’overlay agganciato alla finestra del browser, mentre inset: 0 lo estende su tutti i lati. La proprietà max-height impedisce alle immagini verticali di uscire dallo schermo. Il selettore [hidden] mantiene la finestra realmente nascosta finché JavaScript non la apre.

Caricare il JavaScript senza plugin

Crea nel tema child una cartella chiamata js e al suo interno un file denominato lightbox.js. Il file può essere modificato tramite FTP, Gestione file dell’hosting o un ambiente di sviluppo locale.

Passo 1: inserire il codice JavaScript

Nel file lightbox.js incolla questo codice:

document.addEventListener('DOMContentLoaded', () => {
const overlay = document.querySelector('.wp-lightbox-overlay');
const image = document.querySelector('.wp-lightbox-image');
const caption = document.querySelector('.wp-lightbox-caption');
const closeButton = document.querySelector('.wp-lightbox-close');
const previousButton = document.querySelector('.wp-lightbox-prev');
const nextButton = document.querySelector('.wp-lightbox-next');
const items = Array.from(document.querySelectorAll('.wp-lightbox-item'));

if (!overlay || !image || !caption || !items.length) {
return;
}

let currentIndex = 0;
let lastFocusedElement = null;

function showImage(index) {
currentIndex = (index + items.length) % items.length;

const item = items[currentIndex];
const thumbnail = item.querySelector('img');

image.src = item.dataset.full || thumbnail.src;
image.alt = thumbnail.alt || '';
caption.textContent = item.dataset.caption || thumbnail.alt || '';

overlay.hidden = false;
document.body.style.overflow = 'hidden';
}

function closeLightbox() {
overlay.hidden = true;
image.src = '';
document.body.style.overflow = '';

if (lastFocusedElement) {
lastFocusedElement.focus();
}
}

items.forEach((item, index) => {
item.addEventListener('click', () => {
lastFocusedElement = item;
showImage(index);
closeButton.focus();
});
});

closeButton.addEventListener('click', closeLightbox);

previousButton.addEventListener('click', () => {
showImage(currentIndex - 1);
});

nextButton.addEventListener('click', () => {
showImage(currentIndex + 1);
});

overlay.addEventListener('click', (event) => {
if (event.target === overlay) {
closeLightbox();
}
});

document.addEventListener('keydown', (event) => {
if (overlay.hidden) {
return;
}

if (event.key === 'Escape') {
closeLightbox();
}

if (event.key === 'ArrowLeft') {
showImage(currentIndex - 1);
}

if (event.key === 'ArrowRight') {
showImage(currentIndex + 1);
}
});
});

Il codice seleziona tutte le immagini con classe .wp-lightbox-item e le tratta come una singola galleria. Il tasto Esc chiude il lightbox, le frecce sinistra e destra cambiano immagine e il clic sull’area scura chiude la finestra. Il ritorno del focus al pulsante originale evita che l’utente perda la posizione nella pagina.

Passo 2: registrare lo script nel tema child

Apri il file functions.php del tema child e aggiungi il seguente codice:

function backdigit_carica_lightbox() {
wp_enqueue_script(
'backdigit-lightbox',
get_stylesheet_directory_uri() . '/js/lightbox.js',
array(),
'1.0.0',
true
);
}
add_action('wp_enqueue_scripts', 'backdigit_carica_lightbox');

get_stylesheet_directory_uri() punta alla cartella del tema child, quindi il file deve trovarsi esattamente in js/lightbox.js. Il parametro true carica lo script nel footer della pagina, dopo il contenuto HTML, mentre wp_enqueue_script() evita di inserire JavaScript direttamente nell’articolo.

Se il file functions.php contiene già il tag PHP iniziale <?php, non aggiungerne un secondo. Un errore di sintassi nel file può rendere inutilizzabile il sito, perciò è consigliabile conservare un backup prima della modifica.

Verificare il lightbox su desktop e smartphone

Dopo aver pubblicato la pagina, verifica che il clic su ogni miniatura apra l’immagine corretta e che la didascalia corrisponda alla foto. Controlla anche il comportamento con tastiera usando Tab, Esc, Freccia sinistra e Freccia destra.

Su smartphone, prova il lightbox con immagini sia orizzontali sia verticali. Il CSS riduce automaticamente l’immagine entro l’area disponibile, ma le prestazioni dipendono dal peso dei file originali e dalla velocità del server.

Se la finestra non si apre, controlla che:

La classe .wp-lightbox-item sia presente sui pulsanti HTML.
Ogni elemento abbia un URL valido nell’attributo data-full.
Il file lightbox.js sia nella cartella js del tema child.
Il percorso usato in functions.php corrisponda al nome reale del file.
La console del browser non mostri errori JavaScript.
La cache di WordPress, del tema o del servizio CDN sia stata svuotata.

Questa implementazione di lightbox immagini WordPress JavaScript è adatta a gallerie contenute e non sostituisce una gestione avanzata con caricamento progressivo, zoom o trascinamento. Per una pagina con molte foto, comprimi le immagini e usa dimensioni proporzionate al layout, mantenendo loading="lazy" sulle miniature.

Potrebbe interessarti anche:

FAQ

Il blocco HTML e il CSS aggiuntivo funzionano anche senza tema child, ma il JavaScript va caricato in modo sicuro. Il tema child resta la soluzione più stabile perché evita la perdita delle modifiche durante gli aggiornamenti.

WordPress può rimuovere o limitare i tag `

Sì, ma i pulsanti HTML usati nell’esempio offrono una gestione migliore di tastiera e accessibilità rispetto a un semplice elemento <div> cliccabile.

Sì, purché il blocco HTML sia mantenuto nella pagina e il file JavaScript venga caricato dal tema child. Il percorso dell’area CSS può cambiare in base al tema a blocchi utilizzato.

Modifica la proprietà background di .wp-lightbox-overlay nel CSS. Il valore rgb(0 0 0 / 90%) crea uno sfondo nero con trasparenza del 90%.

Altri articoli di questa serie: