onload

Uruchamia kod JavaScript, gdy zasób skończy się wczytywać: cała strona, obraz, ramka, skrypt albo arkusz stylów.

Dotyczy: <body>, <img>, <iframe>, <script> z atrybutem src, <link> i inne elementy, które wczytują zasób

Na tej stronie

Przykład
Definicja i zastosowanie
Składnia
Kiedy zachodzi zdarzenie load
Więcej przykładów
Obsługa przeglądarek
Dobre praktyki
Powiązane hasła

Przykład

HTML

<p id="status">Wczytywanie okładki…</p>
<img src="/collections/covers/kurs-html-css-od-podstaw.webp"
  alt="Okładka kursu HTML i CSS od podstaw" width="300" height="200"
  onload="
    const size = this.naturalWidth + ' × ' + this.naturalHeight + ' px';
    document.getElementById('status').textContent = 'Okładka wczytana: ' + size;
  ">

Podgląd

Po pobraniu obrazu this.naturalWidth i this.naturalHeight podają prawdziwe wymiary pliku, choć na stronie obraz jest pomniejszony do 300 × 200 pikseli.

Definicja i zastosowanie

Atrybut onload reaguje na zdarzenie load, które zachodzi, gdy element skończy wczytywać swój zasób. Na <img> oznacza to pobrany obraz, na <iframe> wczytany dokument w ramce, na <script src> pobrany i wykonany skrypt, a na <link rel="stylesheet"> gotowy arkusz stylów. Gdy wczytywanie się nie powiedzie, zamiast load zachodzi zdarzenie error, które obsłużysz atrybutem onerror.

Na elemencie <body> atrybut dotyczy całej strony i działa tak samo jak zdarzenie load obiektu window. Zachodzi dopiero wtedy, gdy wczytają się wszystkie obrazy, style, skrypty i ramki, więc na wolnym łączu może minąć sporo czasu. Jeśli skrypt potrzebuje tylko gotowego HTML, lepiej użyć atrybutu defer albo zdarzenia DOMContentLoaded, które zachodzi wcześniej.

W kodzie atrybutu this wskazuje element, np. wczytany obraz z jego prawdziwymi wymiarami naturalWidth i naturalHeight. Zdarzenie load nie wypływa w górę drzewa, więc atrybut ustawiasz bezpośrednio na elemencie, który wczytuje zasób. W większych projektach dodaj obsługę przez addEventListener("load", …).

Składnia

<img src="…" alt="…" onload="kod JavaScript">
<body onload="kod JavaScript">…</body>

Kiedy zachodzi zdarzenie load

<body>
Wczytała się cała strona: HTML, obrazy, style, skrypty i ramki. To samo co load na obiekcie window.
<img>
Obraz został pobrany. Przy loading="lazy" następuje to dopiero, gdy obraz zbliży się do widocznej części strony.
<iframe>
W ramce wczytał się dokument. Zdarzenie zachodzi też przy każdej kolejnej nawigacji wewnątrz ramki.
<script src>
Zewnętrzny skrypt został pobrany i wykonany.
<link rel="stylesheet">
Arkusz stylów został pobrany i przetworzony.

Element	Opis
<body>	Wczytała się cała strona: HTML, obrazy, style, skrypty i ramki. To samo co `load` na obiekcie `window`.
<img>	Obraz został pobrany. Przy `loading="lazy"` następuje to dopiero, gdy obraz zbliży się do widocznej części strony.
<iframe>	W ramce wczytał się dokument. Zdarzenie zachodzi też przy każdej kolejnej nawigacji wewnątrz ramki.
<script src>	Zewnętrzny skrypt został pobrany i wykonany.
<link rel="stylesheet">	Arkusz stylów został pobrany i przetworzony.

Więcej przykładów

Obraz, którego nie udało się wczytać

HTML

<p id="avatar-status">Wczytywanie avatara…</p>
<img src="data:," alt="Avatar użytkownika" width="64" height="64"
  onload="document.getElementById('avatar-status').textContent = 'Avatar wczytany'"
  onerror="document.getElementById('avatar-status').textContent = 'Nie udało się wczytać avatara'">

Podgląd

Adres data:, to celowo uszkodzony obraz, więc zamiast load zachodzi error. Przeglądarka pokazuje tekst alternatywny, a onerror zmienia komunikat.

Strona z onload na body i szybszy DOMContentLoaded

HTML

<body onload="document.getElementById('status').textContent = 'Wczytano wszystko, także obrazy'">
  <p id="status">Wczytywanie…</p>

  <script>
    document.addEventListener('DOMContentLoaded', () => {
      console.log('HTML gotowy, obrazy mogą się jeszcze wczytywać');
    });
  </script>
</body>

Komunikat z DOMContentLoaded pojawi się w konsoli wcześniej, bo to zdarzenie nie czeka na obrazy, style i ramki. Na load warto czekać tylko wtedy, gdy potrzebujesz wszystkich zasobów, np. wymiarów obrazów.

Obsługa przeglądarek

Szeroko dostępne

Działa we wszystkich nowoczesnych przeglądarkach, także na telefonach. Możesz używać bez obaw.

Chrome
Edge
Firefox
Safari

Dobre praktyki

Podawaj obrazom width i height. Przeglądarka zarezerwuje wtedy miejsce, strona nie przeskoczy po wczytaniu obrazu i nie trzeba poprawiać układu w onload.
Kod, który potrzebuje tylko elementów strony, umieść w skrypcie z atrybutem defer, a nie w <body onload>. Uruchomi się szybciej, bez czekania na obrazy.

Powiązane hasła

Widzisz błąd albo brakuje przykładu? Napisz do nas.

Darmowy kursPrzećwicz HTML w kursie HTML i CSSZadania z podpowiedziami, edytor kodu i postępy zapisywane na bieżąco.Zobacz kurs