Kontrolni popis pristupačnosti za React: ARIA, navigacija tipkovnicom, upravljanje fokusom i testiranje (2026.)

# Što ovaj React kontrolni popis pristupačnosti pokriva#

Ovaj React kontrolni popis pristupačnosti napravljen je za developere koji isporučuju produkcijski UI, a ne za audite koji nikad ne završe u kodu. Dobit ćeš konkretne smjernice za implementaciju ARIA-e, navigacije tipkovnicom, upravljanja fokusom i testiranja, uz primjere za forme, modale, izbornike i toast obavijesti.

Pristupačnost je važna jer smanjuje trenje za korisnike i opterećenje supporta, poboljšava konverziju i smanjuje pravni rizik. Svjetska zdravstvena organizacija procjenjuje da otprilike 16% svjetske populacije živi s nekom vrstom invaliditeta, a poboljšanja pristupačnosti često pomažu svima — uključujući napredne korisnike tipkovnice i korisnike na mobitelima.

Ovaj vodič možeš koristiti kao checklistu tijekom PR reviewa i kao CI gate prije releasea. Ako to želiš uskladiti sa širim inženjerskim praksama, upari ga s ponovljivim delivery pipelineom kao što je Proces web razvoja: korak po korak.

# Preduvjeti#

ℹ️ Napomena: Pristupačnost se snažno preklapa sa sigurnošću i kvalitetom. Ako gradiš interne admin panele ili javni SaaS, primijeni jednaku disciplinu na sigurnosne kontrole kao i na a11y gateove. Kao paralelnu checklistu koristi Kontrolni popis sigurnosti web aplikacija.

# Pregled checkliste#

Ovaj visoko‑razinski popis koristi kao vodič za implementaciju i review. Ostatak članka razrađuje svaku stavku kroz primjere koda i testova.

# 1) Prvo semantički HTML, zatim ARIA#

Većina problema pristupačnosti u Reactu nastaje kad se nativni elementi zamijene generičkim kontejnerima. Ako koristiš ispravne elemente, dobiješ ponašanje tipkovnice, upravljanje fokusom i pristupačna imena (accessible names) po defaultu.

Radi ovo po defaultu#

⚠️ Upozorenje: Nemoj dodati role="button" na div i smatrati to gotovim. I dalje ti trebaju keyboard handleri, fokusabilnost i ispravna stanja. U većini slučajeva zamjena s pravim button je brža i sigurnija.

Pravila za pristupačno ime na koja se možeš osloniti#

Za većinu komponenti korisnicima treba pristupačno ime koje odgovara onome što vide. U praksi osiguraj da postoji jedno od sljedećeg:

1. 1
   Vidljivi tekst oznake (label) povezan s elementom.
2. 2
   aria-label za kontrole koje su samo ikona.
3. 3
   aria-labelledby koji pokazuje na vidljivi tekst.

Ako ne znaš koje ime tvoja kontrola ima, provjeri u DevTools Accessibility panelu u pregledniku.

# 2) Checklist za navigaciju tipkovnicom u React UI-ju#

Pristupačnost tipkovnicom je najbrži “signal stvarnog korisnika” koji možeš brzo testirati. Ako UI radi s Tab, Shift + Tab, Enter, Space, Escape i tipkama strelica gdje je relevantno, izbjegavaš velik dio a11y failova.

Keyboard checklist za PR review#

💡 Savjet: Zadrži browser focus ring. Ako dizajn traži custom focus stil, koristi :focus-visible i nemoj uklanjati outline bez zamjene.

Minimalni globalni CSS baseline koji čuva upotrebljivost:

/* Keep default focus, enhance only when keyboard is used */
:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

# 3) Upravljanje fokusom: pravila koja sprječavaju frustraciju korisnika#

Upravljanje fokusom je mjesto gdje React aplikacije često pucaju jer je renderiranje dinamično. Korisnik treba predvidljivu poziciju fokusa nakon radnji poput otvaranja modala, slanja forme ili navigacije.

Pravila (thumb rules) za upravljanje fokusom#

Praktičan obrazac za vraćanje fokusa#

Spremi zadnji fokusirani element, pa ga vrati pri zatvaranju.

import { useEffect, useRef } from "react";
 
export function useRestoreFocus(isOpen) {
  const lastFocusedRef = useRef(null);
 
  useEffect(() => {
    if (isOpen) {
      lastFocusedRef.current = document.activeElement;
    } else if (lastFocusedRef.current && lastFocusedRef.current.focus) {
      lastFocusedRef.current.focus();
    }
  }, [isOpen]);
}

Ovaj hook koristi u modalima i popoverima. Mali je, predvidljiv i sprječava problem “gdje mi je nestao fokus”.

# 4) Forme: oznake, greške i poruke validacije#

Forme su u većini proizvoda a11y površina s najvećim utjecajem jer direktno utječu na signup, checkout i onboarding. Minimalni standard je povezanost labela, smislenih poruka grešaka i najavljivanje promjena validacije.

Ako su forme kompleksne, poveži ovaj dio s skalabilnim obrascima poput React forme u većem opsegu: React Hook Form i Zod.

Checklist za forme#

Konkretan primjer: pristupačan input s porukom greške#

export function TextField({ id, label, error, ...props }) {
  const errorId = error ? `${id}-error` : undefined;
 
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input
        id={id}
        aria-invalid={error ? "true" : "false"}
        aria-describedby={errorId}
        {...props}
      />
      {error ? (
        <p id={errorId}>{error}</p>
      ) : null}
    </div>
  );
}

Ovo pokriva osnove bez pretjerane upotrebe ARIA-e. Label daje pristupačno ime, a aria-describedby povezuje tekst greške.

Obrazac sažetka grešaka za višekoračne ili duge forme#

Sažeci grešaka skraćuju vrijeme do ispravka za korisnike tipkovnice i screen readera jer daju jednu točku navigacije.

Checklist za sažetak grešaka:

1. 1
   Renderiraj sažetak samo kad greške postoje.
2. 2
   Daj mu naslov i listu linkova prema poljima.
3. 3
   Pomakni fokus na sažetak pri submitu ako postoje greške.

import { useEffect, useRef } from "react";
 
export function ErrorSummary({ errors }) {
  const ref = useRef(null);
  const hasErrors = errors.length > 0;
 
  useEffect(() => {
    if (hasErrors) ref.current?.focus();
  }, [hasErrors]);
 
  if (!hasErrors) return null;
 
  return (
    <div tabIndex={-1} ref={ref} aria-labelledby="error-summary-title">
      <h2 id="error-summary-title">Molimo ispravite sljedeće</h2>
      <ul>
        {errors.map((e) => (
          <li key={e.fieldId}>
            <a href={`#${e.fieldId}`}>{e.message}</a>
          </li>
        ))}
      </ul>
    </div>
  );
}

🎯 Ključna poruka: Kod formi, ispravno označavanje i povezivanje grešaka sprječavaju “tihe” kvarove gdje screen reader korisnik čuje “edit text”, ali nikad ne čuje što je polje ili zašto je neispravno.

# 5) Modali: semantika dijaloga, focus trap i zatvaranje na Escape#

Modali su najčešći izvor keyboard trapova. Pristupačan modal mora se ponašati kao privremeni fokusni kontekst, a zatim vratiti korisnika tamo gdje je bio.

Checklist za modale#

Minimalna struktura React modala#

Ovaj primjer koristi role="dialog" i aria-modal="true". Prikazuje označavanje i postavljanje fokusa. Za puni focus trapping razmisli o maloj ovisnosti poput react-focus-lock ili headless UI biblioteci koja ispravno implementira WAI-ARIA obrasce.

import { useEffect, useRef } from "react";
import { useRestoreFocus } from "./useRestoreFocus";
 
export function Modal({ isOpen, title, onClose, children }) {
  const titleId = "modal-title";
  const ref = useRef(null);
 
  useRestoreFocus(isOpen);
 
  useEffect(() => {
    if (!isOpen) return;
    const node = ref.current;
    const first = node?.querySelector(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    first?.focus();
  }, [isOpen]);
 
  useEffect(() => {
    if (!isOpen) return;
    const onKeyDown = (e) => {
      if (e.key === "Escape") onClose();
    };
    document.addEventListener("keydown", onKeyDown);
    return () => document.removeEventListener("keydown", onKeyDown);
  }, [isOpen, onClose]);
 
  if (!isOpen) return null;
 
  return (
    <div role="presentation">
      <div
        role="dialog"
        aria-modal="true"
        aria-labelledby={titleId}
        ref={ref}
      >
        <h2 id={titleId}>{title}</h2>
        <button type="button" onClick={onClose} aria-label="Close dialog">
          Close
        </button>
        {children}
      </div>
    </div>
  );
}

⚠️ Upozorenje: Ako ne zarobiš fokus, korisnici mogu Tabom otići na stranicu iza modala, što stvara zbunjujuće i često neupotrebljivo iskustvo. Ispravan focus trap obično vrijedi jedne ovisnosti.

# 6) Izbornici: uloge, roving tabindex i tipke strelica#

Izbornici nisu samo stilizirane liste. Ako izbornik implementiraš kao composite widget, moraš pratiti očekivano ponašanje tipkovnice. Ako ti trebaju samo navigacijski linkovi, jednostavna lista linkova često je pristupačnija od punog menu widgeta.

Prvo odluči što gradiš#

Checklist za akcijski izbornik#

Primjer roving tabindex za stavke izbornika#

Tab ostaje na okidaču, a unutar izbornika koristiš strelice.

import { useEffect, useRef, useState } from "react";
 
export function ActionMenu({ items }) {
  const [open, setOpen] = useState(false);
  const [activeIndex, setActiveIndex] = useState(0);
  const triggerRef = useRef(null);
  const menuRef = useRef(null);
 
  useEffect(() => {
    if (!open) return;
    const node = menuRef.current?.querySelector('[role="menuitem"][tabindex="0"]');
    node?.focus();
  }, [open]);
 
  const onKeyDown = (e) => {
    if (!open) return;
    if (e.key === "Escape") {
      setOpen(false);
      triggerRef.current?.focus();
    }
    if (e.key === "ArrowDown") {
      e.preventDefault();
      setActiveIndex((i) => (i + 1) % items.length);
    }
    if (e.key === "ArrowUp") {
      e.preventDefault();
      setActiveIndex((i) => (i - 1 + items.length) % items.length);
    }
  };
 
  return (
    <div onKeyDown={onKeyDown}>
      <button
        ref={triggerRef}
        type="button"
        aria-haspopup="menu"
        aria-expanded={open ? "true" : "false"}
        onClick={() => setOpen((v) => !v)}
      >
        Actions
      </button>
 
      {open ? (
        <div role="menu" ref={menuRef} aria-label="Actions menu">
          {items.map((item, idx) => (
            <button
              key={item.id}
              type="button"
              role="menuitem"
              tabIndex={idx === activeIndex ? 0 : -1}
              onFocus={() => setActiveIndex(idx)}
              onClick={() => {
                item.onSelect();
                setOpen(false);
                triggerRef.current?.focus();
              }}
            >
              {item.label}
            </button>
          ))}
        </div>
      ) : null}
    </div>
  );
}

Ovo je pojednostavljeni obrazac. Za produkciju ti još trebaju click-outside handling, pozicioniranje i možda typeahead navigacija.

# 7) Toastovi i obavijesti: najavi bez otimanja fokusa#

Toastovi su prolazni UI. Cilj pristupačnosti je najaviti poruku asistivnoj tehnologiji bez pomicanja fokusa i bez prisiljavanja korisnika na interakciju.

Checklist za toast#

Pristupačan toast kontejner s live regijom#

Koristi wrapper live regije. Za većinu info toastova aria-live="polite" je sigurnije. Za kritične probleme koristi role="alert".

export function ToastRegion({ toasts }) {
  return (
    <div aria-live="polite" aria-relevant="additions text">
      {toasts.map((t) => (
        <div key={t.id} role={t.variant === "error" ? "alert" : undefined}>
          <p>{t.message}</p>
          {t.dismissible ? (
            <button type="button" onClick={t.onDismiss} aria-label="Dismiss notification">
              Dismiss
            </button>
          ) : null}
        </div>
      ))}
    </div>
  );
}

💡 Savjet: Ako toast ima link poput “Undo”, neka bude dostupan tipkovnicom, ali ga nemoj automatski fokusirati. Korisnici trebaju sami odlučiti žele li interakciju.

# 8) ARIA pravila koja trebaš provoditi u code reviewu#

ARIA je moćna, ali lako se zloupotrebljava. Tretiraj ova pravila kao stavku checkliste u svakom PR-u koji uvodi custom UI komponente.

Tablica ARIA “do” i “do not”#

Praktična pitanja za review:

1. 1
   Ima li svaki interaktivni element pristupačno ime koje odgovara tekstu u UI-ju?
2. 2
   Ako se koristi ARIA uloga, odgovara li keyboard ponašanje očekivanju korisnika za tu ulogu?
3. 3
   Jesu li aria-* stanja kontrolirana i ispravno ažurirana?

# 9) Automatizirano testiranje: axe u unit i E2E testovima, plus Playwright keyboard testovi#

Automatizirano testiranje hvata regresije rano. U praksi želiš:

• A11y provjere na razini komponente u test runneru ili Storybooku.
• E2E provjere za ključne stranice i tokove.
• Testove ponašanja tipkovnice koje axe ne može u potpunosti validirati.

Alati i što hvataju#

Primjer Playwright + axe#

Ovaj obrazac pokreće axe na stranici i ruši test ako postoje kršenja.

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";
 
test("settings page has no axe violations", async ({ page }) => {
  await page.goto("/settings");
 
  const results = await new AxeBuilder({ page })
    .exclude('[data-test="third-party-widget"]')
    .analyze();
 
  expect(results.violations).toEqual([]);
});

Exclusions drži rijetkima i opravdanima. Ako moraš excludeati, priloži ticket i datum uklanjanja u procesu code reviewa.

Primjer Playwright testa navigacije tipkovnicom#

Testiraj modal flow end-to-end: otvori, fokus je unutra, Escape zatvara, fokus se vraća.

import { test, expect } from "@playwright/test";
 
test("modal traps focus and restores focus on close", async ({ page }) => {
  await page.goto("/account");
 
  const openButton = page.getByRole("button", { name: "Open dialog" });
  await openButton.focus();
  await page.keyboard.press("Enter");
 
  await expect(page.getByRole("dialog", { name: "Account details" })).toBeVisible();
 
  await page.keyboard.press("Escape");
  await expect(page.getByRole("dialog", { name: "Account details" })).toBeHidden();
 
  await expect(openButton).toBeFocused();
});

Ovo je tip testa koji sprječava regresije kad netko refaktorira interne dijelove modala.

# 10) Ugradi provjere pristupačnosti u CI#

CI je mjesto gdje tvoja React checklist pristupačnosti postaje provediva. Cilj je zaustaviti regresije prije mergea, a ne generirati izvještaje koje nitko ne čita.

Preporučene CI faze#

Primjer GitHub Actions joba za Playwright i axe#

Neka bude minimalno i deterministično.

# CI steps overview
npm ci
npm run build
npm run start:test &
 
# wait for server, then run playwright
npx playwright install --with-deps
npm run test:e2e

U test:e2e skripti pokreni Playwright s manjom project matricom na PR-ovima i većom na noćnim buildovima.

⚠️ Upozorenje: Ako su E2E testovi flaky, timovi će ih isključiti. Stabiliziraj selectore, wait uvjete i testne podatke prije nego uvedeš stroge a11y gateove.

# Česte zamke i kako ih izbjeći#

1. 1
   Globalno uklanjanje focus outlinea — Koristi :focus-visible i zadrži snažan indikator.
2. 2
   Korištenje ARIA-e kao dekoracije — ARIA mora odražavati ponašanje. Ako dodaš role="menu", moraš implementirati pravila tipkovnice za meni.
3. 3
   Nevraćanje fokusa nakon zatvaranja modala — Spremi opener element i vrati fokus, posebno u višekoračnim tokovima.
4. 4
   Placeholder kao label — Uvijek koristi pravi label. Placeholder je hint, ne ime.
5. 5
   Auto-dismiss kritičnih grešaka — Error toastovi ne smiju nestati prije nego korisnik može reagirati.

# Ključne poruke#

• Preferiraj semantički HTML i dodaj ARIA samo kad implementiraš kompletno očekivano ponašanje za taj widget.
• Osiguraj potpunu podršku za tipkovnicu: Tab redoslijed, vidljiv fokus, Escape za zatvaranje i navigaciju strelicama gdje obrazac to zahtijeva.
• Implementiraj predvidljivo upravljanje fokusom: prebaci fokus u modale, zarobi ga i vrati na okidač pri zatvaranju.
• Učini forme robusnima: labeli, aria-describedby za greške, aria-invalid za neispravna polja i sažetak grešaka za duge forme.
• Dodaj automatizirane gateove: axe provjere za ključne rute i Playwright keyboard testove za kritične tokove, provedeno kroz CI.

# Zaključak#

React kontrolni popis pristupačnosti funkcionira samo ako je ponovljiv: komponente semantika‑prvo, konzistentno ponašanje tipkovnice, disciplinirano upravljanje fokusom i CI testovi koji sprječavaju regresije. Ako želiš pomoć u auditu postojeće React ili Next.js aplikacije ili ti treba komponentna biblioteka koja a11y ugrađuje po defaultu, Samioda može implementirati obrasce, testove i CI gateove kao dio tvog delivery pipelinea. Javi se pa ćemo pregledati ključne tokove, definirati praktičnu checklistu za tvoj proizvod i isporučiti poboljšanja bez usporavanja releaseova.