Nota bene

Questa pagina è stata tradotta automaticamente e supervisionata da un maintainer. Un’ulteriore revisione da parte della community sarebbe comunque utile. Migliora questa traduzione.

Il componente browser integrato <img> ti permette di incorporare un’immagine.

<img src="photo.jpg" alt="Una persona che cammina in un parco" />

Reference

<img>

Per visualizzare un’immagine, renderizza il componente browser integrato <img>.

<img src="photo.jpg" alt="Una persona che cammina in un parco" />

Vedi altri esempi sotto.

Props

<img> supporta tutte le props comuni degli elementi.

  • alt: una stringa. Specifica il testo alternativo dell’immagine. Usa una stringa vuota per un’immagine puramente decorativa.
  • crossOrigin: una stringa. Specifica la policy CORS da usare quando viene recuperata l’immagine. I valori possibili sono anonymous e use-credentials.
  • decoding: una stringa. Suggerisce se il browser dovrebbe attendere di decodificare l’immagine prima di presentare altro contenuto. I valori possibili sono async, sync e auto (il valore predefinito).
  • fetchPriority: una stringa. Suggerisce una priorità relativa per il recupero dell’immagine. I valori possibili sono high, low e auto (il valore predefinito). Durante la renderizzazione lato server, fetchPriority="low" impedisce anche a React di precaricare automaticamente l’immagine.
  • height: un numero o una stringa. Specifica l’altezza con cui viene visualizzata l’immagine.
  • loading: una stringa. Specifica se il browser dovrebbe rinviare il caricamento dell’immagine finché non è vicina al viewport. I valori possibili sono eager (il valore predefinito) e lazy. Impostare loading="lazy" impedisce a React di precaricare automaticamente l’immagine.
  • onError: una funzione gestore di eventi. Scatta quando il caricamento dell’immagine fallisce.
  • onLoad: una funzione gestore di eventi. Scatta quando il caricamento dell’immagine è completato. Passare onLoad impedisce a React di attendere l’immagine durante un aggiornamento View Transition renderizzato lato client.
  • referrerPolicy: una stringa. Specifica le informazioni sul referrer da inviare quando viene recuperata l’immagine.
  • sizes: una stringa. Specifica le dimensioni dell’immagine per i diversi layout di pagina. Usata insieme a srcSet.
  • src: una stringa. Specifica l’URL dell’immagine.
  • srcSet: una stringa. Specifica una o più sorgenti candidate tra cui il browser può scegliere.
  • useMap: una stringa. Associa l’immagine a una mappa immagine lato client.
  • width: un numero o una stringa. Specifica la larghezza con cui viene visualizzata l’immagine.

Caveats

  • Non passare una stringa vuota a src: potrebbe indurre il browser a richiedere di nuovo la pagina corrente. React mostra un avviso in sviluppo e omette l’attributo. Per non visualizzare alcuna immagine, ometti <img> o passa null a src.
  • <img> non può avere children né usare dangerouslySetInnerHTML. React solleva un errore se passi una delle due cose.
  • fetchPriority="low" non impedisce a React di attendere che l’immagine venga caricata e decodificata durante un aggiornamento View Transition renderizzato lato client. Usa loading="lazy" o un gestore onLoad per rinunciare a questo comportamento.

Usage

Visualizzare un’immagine

Passa l’URL dell’immagine a src e una descrizione testuale a alt:

export default function Profile() {
  return (
    <img
      src="https://react.dev/images/docs/scientists/yXOvdOSs.jpg"
      alt="Hedy Lamarr"
      width={100}
      height={100}
    />
  );
}

Specifica width e height quando conosci le dimensioni dell’immagine, così il browser può riservare lo spazio prima che l’immagine venga caricata. Per un’immagine decorativa, passa alt="" in modo che gli screen reader la ignorino.

Controllare il precaricamento delle immagini durante la renderizzazione lato server

Durante la renderizzazione lato server, per impostazione predefinita React genera automaticamente un hint di preload per un <img>. Questo può permettere al browser di iniziare a recuperare l’immagine prima di incontrare l’<img> nell’HTML renderizzato.

Aggiungi loading="lazy" o fetchPriority="low" a un’immagine che non dovrebbe ricevere questo hint:

function ProductPage() {
  return (
    <>
      <img src="hero.jpg" alt="Prodotto in evidenza" />
      <img src="thumbnail.jpg" alt="Prodotto correlato" loading="lazy" />
      <img src="secondary.jpg" alt="Un altro prodotto" fetchPriority="low" />
    </>
  );
}

In questo esempio, React genera un hint di preload solo per hero.jpg. A seconda dell’API del server o del framework, React potrebbe renderizzare l’equivalente di questo elemento:

<link rel="preload" as="image" href="hero.jpg" />

React potrebbe invece fornire lo stesso hint nell’intestazione Link della risposta. Le altre due immagini mantengono le loro props loading e fetchPriority nell’HTML renderizzato, ma React non genera hint di preload per queste immagini. La prop loading="lazy" chiede al browser di rinviare il caricamento di un’immagine finché non si avvicina al viewport. La prop fetchPriority="low" permette all’immagine di caricarsi immediatamente, ma dice al browser di recuperarla con una priorità più bassa.

React inoltre non precarica automaticamente un’immagine quando si trova all’interno di un elemento <picture> o <noscript>, o quando il suo src o srcSet è un data URL.

Se renderizzi un’immagine attraverso un framework o una libreria di componenti, consulta la sua documentazione per il comportamento predefinito. React decide se generare un precaricamento automatico in base alle props dell’<img> sottostante. Ad esempio, un componente immagine potrebbe aggiungere loading="lazy" per impostazione predefinita e fornire un’opzione separata per precaricare esplicitamente le immagini selezionate.

Per creare un hint di preload esplicito, chiama preload.

Attendere un’immagine durante una View Transition

Durante un aggiornamento <ViewTransition> renderizzato lato client, React potrebbe attendere che un’immagine si carichi e venga decodificata prima di avviare l’animazione. Questo si applica quando viene renderizzato un nuovo <img> con un src non vuoto, o quando src o srcSet di un’immagine esistente cambia. L’immagine deve trovarsi nel sottoalbero del <ViewTransition> e non deve avere loading="lazy" né un gestore onLoad. React non attende le immagini durante gli aggiornamenti sincroni.

Quando un boundary Suspense rivela contenuto in streaming all’interno di un <ViewTransition>, React potrebbe anche attendere le immagini visibili con un src non vuoto che non hanno loading="lazy". React smette di attendere dopo un timeout, così che un’immagine lenta non blocchi l’aggiornamento all’infinito.

In questo esempio, il boundary Suspense è avvolto in un <ViewTransition> e mostra un placeholder del profilo finché il ritratto non si è caricato.

Per confronto, il secondo pulsante inserisce la stessa card direttamente nel DOM. La card appare immediatamente, e il browser visualizza l’immagine dopo che si è caricata:

import { ViewTransition, Suspense, useState, startTransition } from 'react';
import { freshImageUrl } from './image.js';
import VanillaProfile from './VanillaProfile.js';

function Profile({ src }) {
  return (
    <div className="card">
      <img src={src} alt="Jack Pope" width={80} height={80} />
      <p>Jack Pope</p>
    </div>
  );
}

function ProfilePlaceholder() {
  return (
    <div className="card">
      <div className="avatar-placeholder" />
      <p className="name-placeholder">&nbsp;</p>
    </div>
  );
}

export default function App() {
  const [src, setSrc] = useState(null);
  return (
    <>
      <button
        onClick={() => {
          startTransition(() => {
            setSrc(freshImageUrl());
          });
        }}>
        Mostra profilo
      </button>
      {src && (
        <ViewTransition>
          <Suspense fallback={<ProfilePlaceholder />}>
            <Profile src={src} />
          </Suspense>
        </ViewTransition>
      )}
      <hr />
      <VanillaProfile />
    </>
  );
}
Previous<textarea>
Next<link>