Tooltip w Tailwind CSS: jak zbudować dostępną podpowiedź

Tooltip pomaga, gdy krótko objaśnia element, którego nazwa jest już zrozumiała, na przykład skrót przy polu formularza. Nie ukrywaj w tooltipie jedynej instrukcji, warunku zakupu ani komunikatu o błędzie, ponieważ użytkownik może nie odkryć podpowiedzi.

Etykieta nazywa kontrolkę, widoczny tekst pomocniczy przekazuje instrukcję, a tooltip dodaje krótki opis po fokusie lub najechaniu. Disclosure, czyli przycisk ujawniający treść po aktywacji, lepiej pasuje do dłuższego opisu lub treści dostępnej na dotyku. Tooltip nie powinien zawierać linków ani kontrolek wymagających fokusu.

Tabela rozdziela nazwę kontrolki, konieczną instrukcję i dodatkowy opis. Jeśli tooltip jest częścią szablonu sklepu, optymalizacja szybkości WooCommerce może objąć analizę elementów interfejsu w ramach prac nad sklepem.

WAI-ARIA APG opisuje tooltip jako podpowiedź pojawiającą się przy fokusie lub najechaniu. Dokument oznacza wzorzec jako będący w toku i bez konsensusu grupy roboczej; sprawdziliśmy go w październiku 2026 r.

Użyj przycisku jako wyzwalacza, jeśli podpowiedź otwiera ikona, ponieważ przycisk natywnie przyjmuje fokus i obsługuje klawiaturę. Przykład React wiąże opis z wyzwalaczem przez `aria-describedby`, a stan widoczności obsługuje po najechaniu, fokusie i Escape.

import { useId, useState } from "react";

export function NipTooltip() {
  const id = useId();
  const [open, setOpen] = useState(false);
  const [dismissed, setDismissed] = useState(false);

  function dismissWithEscape(event) {
    if (event.key === "Escape" && open) {
      event.preventDefault();
      setOpen(false);
      setDismissed(true);
    }
  }

  function leaveActiveArea() {
    setOpen(false);
    setDismissed(false);
  }

  return (
    <span
      className="relative inline-flex"
      onMouseEnter={() => !dismissed && setOpen(true)}
      onMouseLeave={leaveActiveArea}
      onFocus={() => !dismissed && setOpen(true)}
      onBlur={(event) => {
        if (!event.currentTarget.contains(event.relatedTarget)) leaveActiveArea();
      }}
      onKeyDown={dismissWithEscape}
    >
      <button
        type="button"
        aria-label="Informacja o numerze NIP"
        aria-describedby={id}
        className="inline-flex size-6 items-center justify-center rounded-full text-sm font-semibold text-slate-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-700"
      >
        <span aria-hidden="true">i</span>
      </button>
      <span
        id={id}
        role="tooltip"
        className={`absolute bottom-full left-1/2 z-20 w-max max-w-[min(20rem,calc(100vw_-_2rem))] -translate-x-1/2 rounded bg-slate-950 px-3 py-2 text-sm text-white shadow-lg transition-opacity ${open ? "visible pointer-events-auto opacity-100" : "invisible pointer-events-none opacity-0"}`}
      >
        NIP wpisz bez spacji i myślników.
      </span>
    </span>
  );
}

Tooltip przylega do przycisku, ponieważ `bottom-full` nie tworzy szczeliny między elementami. Jeśli projekt wymaga widocznego odstępu, dodaj przezroczysty obszar łączący, na przykład pseudoelement rodzica, albo opóźnione zamykanie anulowane po wejściu kursorem na treść. Samo `pointer-events-auto` nie naprawia przerwy.

`useId()` nadaje każdej instancji unikalny identyfikator, dzięki czemu `aria-describedby` nie wskazuje przypadkowo opisu innego przycisku. Dla instrukcji wymaganej do wypełnienia formularza użyj widocznego tekstu pod polem, a nie opisu ukrytego przy ikonie.

Rodzic z klasą `relative` wyznacza punkt odniesienia dla tooltipa ustawionego przez `absolute`. Klasa `bottom-full` umieszcza opis nad wyzwalaczem, a `left-1/2` z `-translate-x-1/2` centruje go poziomo.

React steruje stanem widoczności, a klasy Tailwind określają wygląd. `visible` i `opacity-100` pokazują treść, natomiast `invisible`, `pointer-events-none` i `opacity-0` ją ukrywają. Przy otwarciu `pointer-events-auto` pozwala przejść wskaźnikiem na treść, o ile rodzic utrzymuje ciągły obszar aktywny.

Klasa arbitralna `max-w-[min(20rem,calc(100vw_-_2rem))]` ogranicza szerokość do mniejszej z wartości: `20rem` lub szerokości okna pomniejszonej o marginesy. Podkreślenia zastępują spacje w wartości zapisanej w klasie. Składnię wariantów `hover:` i `focus-visible:` opisuje dokumentacja stanów Tailwind CSS.

Tailwind wykrywa pełne tokeny klas w plikach źródłowych i nie oblicza interpolacji JavaScript. Zapis `opacity-${open ? 100 : 0}` może nie wygenerować reguł. Umieść pełne nazwy klas w kodzie, a dla pominiętych źródeł Tailwind CSS 4 użyj dyrektywy `@source`; w starszej konfiguracji sprawdź pole `content` w `tailwind.config.js`.

Użytkownik klawiatury powinien zobaczyć podpowiedź po ustawieniu fokusu, a fokus powinien pozostać na wyzwalaczu. Dodaj widoczny obrys przez `focus-visible:outline-*` i obsłuż Escape, aby zamknąć tooltip.

Atrybut `aria-describedby` łączy wyzwalacz z opisem, a element opisu otrzymuje `role="tooltip"`. W przykładzie relacja istnieje także wtedy, gdy podpowiedź jest wizualnie ukryta, dzięki czemu czytnik ekranu może powiązać opis z przyciskiem. Sprawdź odczyt w docelowych kombinacjach przeglądarki i czytnika ekranu.

Po Escape nie otwieraj tooltipa ponownie, gdy fokus nadal pozostaje na przycisku. Stan `dismissed` z przykładu zapamiętuje zamknięcie i resetuje je po opuszczeniu całego aktywnego obszaru. WAI-ARIA APG zaleca zamknięcie Escape, pozostawienie fokusu na wyzwalaczu i powiązanie opisu przez `aria-describedby`; wzorzec jest oznaczony jako praca w toku.

Na dotyku zastosuj osobny przycisk disclosure, który jawnie pokazuje i ukrywa treść. Atrybut `aria-expanded` komunikuje stan, a `aria-controls` wskazuje element sterowany przyciskiem.

import { useId, useState } from "react";

export function NipHelp() {
  const id = useId();
  const [open, setOpen] = useState(false);

  return (
    <div>
      <button
        type="button"
        aria-expanded={open}
        aria-controls={id}
        onClick={() => setOpen((value) => !value)}
      >
        Informacja o numerze NIP
      </button>
      <div id={id} hidden={!open}>
        NIP wpisz bez spacji i myślników.
      </div>
    </div>
  );
}

Disclosure nie otrzymuje `role="tooltip"`, ponieważ jest osobnym wzorcem interakcji. Użytkownik dotykowy widzi nazwany przycisk i sam decyduje, czy odsłonić treść.

Na wąskim ekranie zachowaj w viewport treść i wyzwalacz, zawijaj dłuższe zdania i unikaj poziomego przewijania. Jeśli opis zawiera linki lub inne kontrolki, użyj wzorca popovera albo dialogu, który obsługuje interakcje i fokus.

Tabela pokazuje, co sprawdzić dla każdego sposobu obsługi. Zmniejszenie szerokości okna nie odtwarza wszystkich zdarzeń dotykowych.

Przetestuj dotyk na urządzeniu albo w emulacji zdarzeń dotykowych. Dla szablonu WordPress zapisz wynik osobno dla widoków, w których tooltip może się pojawiać.

Tooltip może być przycinany przez przodka z `overflow`, zasłonięty przez inny kontekst stosu albo pozbawiony wygenerowanej reguły CSS. Sprawdź Styles i Computed w DevTools, aby ustalić, czy klasa nie dostała reguły, została nadpisana czy jest przycinana.

Tabela pomaga powiązać widoczny objaw z kontrolą w DOM lub CSS. Sprawdzaj rodzica tooltipa i jego kolejnych przodków, a nie tylko sam element.

Tabela porządkuje typowe kontrole. Samo zwiększenie `z-index` nie usuwa przycinania przez `overflow` i nie zawsze przebija kontekst stosu utworzony przez rodzica.

W motywie WordPress sprawdź style kolumny, karty lub widgetu, w którym znajduje się komponent. Jeśli tooltip jest w przewijanym kontenerze lub nagłówku, rozważ renderowanie warstwy poza przodkiem przez portal. Gdy HTML zawiera klasę, ale arkusz nie ma jej reguły, sprawdź pełny token i ścieżki wykrywania Tailwind.

Sprawdź tooltip osobno myszą, klawiaturą, dotykiem i czytnikiem ekranu, ponieważ wygląd nie potwierdza poprawności wszystkich interakcji. WAI-ARIA APG opisuje zamknięcie Escape oraz utrzymanie tooltipa, gdy kursor znajduje się nad wyzwalaczem lub treścią.

• Mysz: najedź na wyzwalacz, przejdź kursorem na opis i sprawdź, czy komponent się nie zamyka.
• Klawiatura: użyj Tab, Shift+Tab i Escape; potwierdź, że fokus zostaje na wyzwalaczu.
• Dotyk: otwórz i zamknij disclosure; sprawdź zmianę `aria-expanded`.
• Czytnik ekranu: sprawdź nazwę oraz opis na docelowej kombinacji urządzeń.
• Wąski ekran: sprawdź zawijanie tekstu, położenie i poziome przewijanie.
• Motyw strony: sprawdź `overflow` oraz konteksty stosu rodziców.

Perspektywa KC Mobile. W istniejącym motywie WordPress tooltip może mieć poprawne klasy, a mimo to znikać przez `overflow` karty albo kontekst stosu widgetu. Przy diagnozie sprawdź ścieżkę przodków w DOM i widoczność komponentu w docelowym szablonie.

Jeśli tooltip działa w sklepie, a jego poprawki wchodzą w zakres prac nad frontendem, optymalizacja działania sklepu WooCommerce może objąć analizę szablonu i komponentów. Przy ocenie szybkości strony WordPress porównaj też diagnostykę Core Web Vitals. Przykład powiadomienia o innym sposobie interakcji znajdziesz w materiale o toastach w Tailwind CSS.

• Tailwind CSS toast: jak wdrożyć powiadomienia, które są czytelne i dostępne
• Optymalizacja stron z dynamicznymi tabelami danych pod szybkość i SEO
• Cache na stronie www: jak działa i kiedy przyspiesza ładowanie
• Cloudflare - co to jest, jak działa i kiedy przydaje się firmie