Kurs JavaScript i React · Moduł 15: Wzorce i architektura

Headless Components - Oddzielenie logiki od prezentacji

7 min czytania ·
W tej lekcji7

Kokpit i panel inżynierski potrzebują tej samej listy rozwijanej: otwieranie, zamykanie, wybór opcji, obsługa klawiatury i atrybuty dostępności. Kokpit chce jednak prostego przycisku, a inżynierowie kosmicznego menu z ikonami. Dwa komponenty to dwie kopie trudnej logiki i dwa miejsca na błędy. Lepszy jest uniwersalny moduł sterowania, który podłączysz do dowolnego panelu. To właśnie idea Headless Components: komponentów, które zawierają całą logikę, ale zero UI.

Czym są Headless Components?

Headless Component to komponent lub hook, który:

  1. Zarządza stanem i logiką (otwieranie/zamykanie, selekcja, nawigacja)
  2. NIE renderuje żadnego JSX, czyli nie ma własnego wyglądu
  3. Oddaje kontrolę nad UI konsumentowi przez propsy, render props lub hooki

Najczęściej to po prostu custom hook, jak useCrew z poprzedniej lekcji, tylko zamiast danych z API zarządza zachowaniem interfejsu. Zbudujmy headless dropdown krok po kroku. Najpierw stan listy i trzy proste akcje:

// Headless Dropdown: cała logika, zero UI
function useDropdown(options) {
  const [isOpen, setIsOpen] = useState(false);
  const [selectedIndex, setSelectedIndex] = useState(-1);
  const [selectedOption, setSelectedOption] = useState(null);

  const toggle = () => setIsOpen(prev => !prev);
  const close = () => setIsOpen(false);

  const select = (index) => {
    setSelectedIndex(index);
    setSelectedOption(options[index]);
    setIsOpen(false);
  };

Nic z tego nie pojawi się jeszcze na ekranie: to czysta logika, która zadziała w każdym wyglądzie. Teraz obsługa klawiatury, czyli część najczęściej pomijana przy pisaniu dropdownu od zera:

  // Nawigacja klawiaturą
  const handleKeyDown = (e) => {
    if (e.key === 'ArrowDown') {
      e.preventDefault();
      setSelectedIndex(prev => Math.min(prev + 1, options.length - 1));
    } else if (e.key === 'ArrowUp') {
      e.preventDefault();
      setSelectedIndex(prev => Math.max(prev - 1, 0));
    } else if (e.key === 'Enter' && isOpen && selectedIndex >= 0) {
      e.preventDefault();
      select(selectedIndex);
    } else if (e.key === 'Escape') {
      close();
    }
  };

Strzałki przesuwają indeks w granicach listy, Enter zatwierdza wybór, a Escape zamyka listę. e.preventDefault() wyłącza domyślne reakcje przeglądarki: strzałki nie przewijają strony, a Enter nie dokłada zwykłego kliknięcia przycisku, które od razu otworzyłoby listę z powrotem. Zamkniętą listę otwiera właśnie to kliknięcie, bo na przycisku Enter i spacja działają jak klik myszą. W tej uproszczonej wersji jeden indeks służy i do podświetlenia, i do zaznaczenia, a biblioteki rozdzielają te dwie rzeczy. Na koniec hook zwraca wszystko, czego potrzebuje widok, w tym dwie funkcje zwracające gotowe zestawy propsów:

  return {
    isOpen, selectedIndex, selectedOption,
    toggle, close, select, handleKeyDown,
    getToggleProps: () => ({
      onClick: toggle,
      onKeyDown: handleKeyDown,
      'aria-expanded': isOpen,
      'aria-haspopup': 'listbox',
    }),
    getOptionProps: (index) => ({
      onClick: () => select(index),
      'aria-selected': selectedIndex === index,
      role: 'option',
    }),
  };
}

getToggleProps() oddaje onClick, onKeyDown, aria-expanded i aria-haspopup, a getOptionProps(index) dodaje każdej opcji role i aria-selected. Konsument rozkłada te obiekty operatorem spread i nie musi pamiętać o dostępności. Takie funkcje nazywa się prop getters, a spotkasz je choćby w bibliotece Downshift.

Użycie headless dropdown z dowolnym UI

Klucz do headless components: ten sam hook, różne wyglądy. Pierwsza wersja to zwykły przycisk i lista, bez żadnych ozdobników:

// Wersja 1: Prosty dropdown
function SimpleDropdown({ options, label }) {
  const dropdown = useDropdown(options);

  return (
    <div className="simple-dropdown">
      <button {...dropdown.getToggleProps()}>
        {dropdown.selectedOption || label}
      </button>
      {dropdown.isOpen && (
        <ul role="listbox">
          {options.map((opt, i) => (
            <li key={i} {...dropdown.getOptionProps(i)}>
              {opt}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Druga wersja korzysta z identycznego hooka, ale buduje kosmiczne menu z ikonami i strzałką, która pokazuje stan listy:

// Wersja 2: Kosmiczny dropdown z ikonami
function SpaceDropdown({ options, icons }) {
  const dropdown = useDropdown(options);

  return (
    <div className="space-dropdown">
      <button type="button" {...dropdown.getToggleProps()} className="space-trigger">
        <span>{dropdown.selectedOption || 'Wybierz system'}</span>
        <span>{dropdown.isOpen ? '▲' : '▼'}</span>
      </button>
      {dropdown.isOpen && (
        <div className="space-menu">
          {options.map((opt, i) => (
            <div key={i} {...dropdown.getOptionProps(i)} className="space-option">
              <span>{icons[i]}</span>
              <span>{opt}</span>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Oba komponenty różnią się tylko JSX-em, a hook nie zmienił się ani o linijkę. Wynik możesz też od razu rozpakować: const { isOpen, selectedOption, getToggleProps, getOptionProps } = useDropdown(options). Zwróć uwagę, że wyzwalaczem znowu jest <button>, choć wygląda zupełnie inaczej niż w pierwszej wersji. Hook dostarcza atrybuty ARIA, ale element wybierasz Ty: <div> nie dostałby fokusu z klawiatury, a nawet z tabIndex={0} i role="button" Enter i spację musiałbyś obsłużyć ręcznie.

Headless Toggle / Disclosure

Kolejny przykład to headless toggle do budowania akordeonów, rozwijanych sekcji i spoilerów. Ten hook jest krótki, bo pilnuje tylko jednej wartości logicznej:

function useToggle(initialState = false) {
  const [isOpen, setIsOpen] = useState(initialState);

  return {
    isOpen,
    toggle: () => setIsOpen(p => !p),
    open: () => setIsOpen(true),
    close: () => setIsOpen(false),
    getToggleProps: () => ({
      onClick: () => setIsOpen(p => !p),
      'aria-expanded': isOpen,
    }),
    getPanelProps: () => ({
      role: 'region',
      hidden: !isOpen,
    }),
  };
}

Na tym samym przełączniku zbudujemy dwa zupełnie różne komponenty. Pierwszy to akordeon, który rozwija opis systemu statku:

// Użycie 1: akordeon
function SystemDetails({ title, children }) {
  const { isOpen, getToggleProps, getPanelProps } = useToggle();

  return (
    <div className="accordion-item">
      <button {...getToggleProps()}>
        {title} {isOpen ? '−' : '+'}
      </button>
      <div {...getPanelProps()}>
        {isOpen && children}
      </div>
    </div>
  );
}

Tooltip wygląda inaczej, ale korzysta z identycznego API hooka, więc logika otwierania i zamykania nie jest powielana:

// Użycie 2: Tooltip
function InfoTooltip({ content, children }) {
  const { isOpen, getToggleProps, getPanelProps } = useToggle();

  return (
    <span className="tooltip-wrapper">
      <button type="button" {...getToggleProps()} className="tooltip-trigger">
        {children}
      </button>
      <span {...getPanelProps()} className="tooltip-content">
        {isOpen && content}
      </span>
    </span>
  );
}

getPanelProps() ustawia hidden i role="region": dzięki hidden zwinięty panel znika także dla czytników ekranu, a nie tylko wizualnie. Wyzwalaczem znowu jest <button>, bo aria-expanded wolno nadać tylko elementom z rolą, takim jak przycisk, a <span> nie dostałby fokusu. Ten sam kształt API znajdziesz w bibliotekach headless pod nazwą Disclosure.

Headless Tabs

Zakładki to trzeci klasyk. Hook pamięta aktywną zakładkę i nadaje role tab oraz tabpanel, które czytniki ekranu rozumieją bez dodatkowych opisów:

function useTabs(tabCount, defaultTab = 0) {
  const [activeTab, setActiveTab] = useState(defaultTab);

  return {
    activeTab,
    setActiveTab,
    getTabProps: (index) => ({
      onClick: () => setActiveTab(index),
      role: 'tab',
      'aria-selected': activeTab === index,
      tabIndex: activeTab === index ? 0 : -1,
    }),
    getPanelProps: (index) => ({
      role: 'tabpanel',
      hidden: activeTab !== index,
    }),
    isActive: (index) => activeTab === index,
  };
}

tabIndex równy 0 tylko dla aktywnej zakładki to technika roving tabindex: klawisz Tab trafia od razu na aktywną zakładkę. Wzorzec zakładek z WAI-ARIA dodaje jeszcze przełączanie strzałkami, do którego przyda się nieużywany na razie parametr tabCount.

Dlaczego headless?

CechaZwykły komponentHeadless Component
UIWbudowane style/JSXZero, TY decydujesz
ReużywalnośćOgraniczona do jednego wygląduNieograniczona
DostępnośćTrzeba implementować ręcznieWbudowane aria-atrybuty
TestowalnośćWymaga renderowaniaTestuj sam hook

Headless UI w ekosystemie React

Biblioteka @headlessui/react (od twórców Tailwind CSS) dostarcza gotowe headless komponenty:

  • Listbox: dropdown z pełną obsługą klawiatury
  • Combobox: autocomplete/search
  • Dialog: modal z focus trap
  • Disclosure: accordion/expandable
  • Menu: dropdown menu
  • Tabs: zakładki

Każdy z nich dostarcza logikę, aria-atrybuty i obsługę klawiatury, ale zero stylowania. Ty dostarczasz cały wygląd. Podobnie działają Radix UI Primitives oraz React Aria od Adobe.

Kiedy używać headless components?

  • Budujesz design system: różne zespoły potrzebują tych samych interakcji, ale różnych stylów
  • Potrzebujesz pełnej dostępności (a11y): headless komponenty mają wbudowane aria-atrybuty
  • Tworzysz komponenty używane w wielu projektach: logika ta sama, style różne
  • Chcesz oddzielić odpowiedzialność: hook = logika, komponent = wygląd

Headless Components działają jak uniwersalny system nawigacyjny statku: logika jest ta sama, ale każdy panel wygląda inaczej, bo każda stacja ma inne potrzeby. Moja rada: własny headless hook pisz dla prostych przełączników, takich jak useToggle. Dropdown, combobox czy dialog z pełną obsługą klawiatury i fokusu to dużo pracy, więc tam sięgnij po sprawdzoną bibliotekę. W następnej lekcji oddamy użytkownikowi komponentu jeszcze więcej kontroli dzięki Inversion of Control i zobaczymy, czym prop getters różnią się od props collection.

Pamiętaj: headless hook to silnik bez kadłuba, a kadłub projektujesz sam.

Kod do tej lekcji: App.jsx
import React, { useState } from 'react';

// === HEADLESS HOOK: useDropdown ===
function useDropdown(options) {
  const [isOpen, setIsOpen] = useState(false);
  const [selectedIndex, setSelectedIndex] = useState(-1);
  const [selectedOption, setSelectedOption] = useState(null);

  const toggle = () => setIsOpen(p => !p);
  const close = () => setIsOpen(false);

  const select = (index) => {
    setSelectedIndex(index);
    setSelectedOption(options[index]);
    setIsOpen(false);
  };

  // preventDefault: strzałki nie przewijają strony, a Enter nie dokłada kliknięcia, które znowu otworzyłoby listę
  const handleKeyDown = (e) => {
    if (e.key === 'ArrowDown') { e.preventDefault(); setSelectedIndex(p => Math.min(p + 1, options.length - 1)); }
    else if (e.key === 'ArrowUp') { e.preventDefault(); setSelectedIndex(p => Math.max(p - 1, 0)); }
    else if (e.key === 'Enter' && isOpen && selectedIndex >= 0) { e.preventDefault(); select(selectedIndex); }
    else if (e.key === 'Escape') close();
  };

  return {
    isOpen, selectedIndex, selectedOption, toggle, close, select, handleKeyDown,
    getToggleProps: () => ({ onClick: toggle, onKeyDown: handleKeyDown, 'aria-expanded': isOpen, 'aria-haspopup': 'listbox' }),
    getOptionProps: (i) => ({ onClick: () => select(i), 'aria-selected': selectedIndex === i, role: 'option' }),
  };
}

// === HEADLESS HOOK: useToggle ===
function useToggle(initial = false) {
  const [isOpen, setIsOpen] = useState(initial);
  return {
    isOpen,
    toggle: () => setIsOpen(p => !p),
    getToggleProps: () => ({ onClick: () => setIsOpen(p => !p), 'aria-expanded': isOpen }),
    getPanelProps: () => ({ role: 'region', hidden: !isOpen }),
  };
}

// === KOMPONENT WIZUALNY 1: prosty dropdown ===
function SimpleDropdown({ options, label }) {
  const dd = useDropdown(options);
  return (
    <div className="dropdown">
      <button className="dd-trigger" {...dd.getToggleProps()}>
        {dd.selectedOption || label} <span>{dd.isOpen ? '\u25B2' : '\u25BC'}</span>
      </button>
      {dd.isOpen && (
        <ul className="dd-menu" role="listbox">
          {options.map((opt, i) => (
            <li key={i} className={"dd-option " + (dd.selectedIndex === i ? "highlighted" : "")} {...dd.getOptionProps(i)}>
              {opt}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

// === KOMPONENT WIZUALNY 2: kosmiczny dropdown (inny wygląd, ta sama logika) ===
function SpaceDropdown({ options, icons, label }) {
  const dd = useDropdown(options);
  return (
    <div className="space-dd">
      <button type="button" className="space-trigger" {...dd.getToggleProps()}>
        <span>{dd.selectedOption || label}</span>
        <span className="arrow">{dd.isOpen ? '\u25B2' : '\u25BC'}</span>
      </button>
      {dd.isOpen && (
        <div className="space-menu">
          {options.map((opt, i) => (
            <div key={i} className={"space-option " + (dd.selectedIndex === i ? "highlighted" : "")} {...dd.getOptionProps(i)}>
              <span className="opt-icon">{icons[i]}</span>
              <span>{opt}</span>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

// === Akordeon na bazie useToggle ===
function AccordionItem({ title, children }) {
  const { isOpen, getToggleProps, getPanelProps } = useToggle();
  return (
    <div className="accordion-item">
      <button className="accordion-header" {...getToggleProps()}>
        {title} <span>{isOpen ? '\u2212' : '+'}</span>
      </button>
      <div className="accordion-body" {...getPanelProps()}>
        {isOpen && <div className="accordion-content">{children}</div>}
      </div>
    </div>
  );
}

// === GŁÓWNY KOMPONENT ===
export default function App() {
  return (
    <div className="app">
      <h1>Demo komponentów headless</h1>
      <p className="subtitle">Te same hooki z logiką, różne wersje wyglądu</p>

      <div className="section">
        <h3>Prosty dropdown (useDropdown)</h3>
        <SimpleDropdown options={['Mars', 'Jowisz', 'Saturn', 'Europa']} label="Wybierz planetę..." />
      </div>

      <div className="section">
        <h3>Kosmiczny dropdown (ten sam useDropdown, inny wygląd)</h3>
        <SpaceDropdown
          options={['Silniki', 'Osłony', 'Nawigacja', 'Uzbrojenie']}
          icons={['SIL', 'OSŁ', 'NAW', 'UZB']}
          label="Wybierz system..."
        />
      </div>

      <div className="section">
        <h3>Akordeon (useToggle)</h3>
        <AccordionItem title="Stan silnika">
          <p>Napęd plazmowy pracuje z wydajnością 94%.</p>
        </AccordionItem>
        <AccordionItem title="Raport osłon">
          <p>Osłony przednie: 78%. Osłony tylne: 100%.</p>
        </AccordionItem>
        <AccordionItem title="Nawigacja">
          <p>Kurs na Alfa Centauri. Czas dotarcia: 4,2 roku.</p>
        </AccordionItem>
      </div>
    </div>
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Czym są Headless Components w kontekście React?

  2. 2. Jaki jest cel metod getToggleProps() i getOptionProps() w headless hooks?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Dokończ dwa headless hooki i dwa wyglądy na nich zbudowane. W useDropdown ___BLANK1___: po wybraniu opcji lista się zamyka (użyj gotowej akcji close). ___BLANK2___: getToggleProps ustawia aria-expanded zgodnie z tym, czy lista jest otwarta. ___BLANK3___: getOptionProps(index) ustawia aria-selected na true tylko dla wybranej opcji (selectedIndex), dla pozostałych false. W useToggle ___BLANK4___: getPanelProps ukrywa panel atrybutem hidden, gdy przełącznik jest zamknięty. ___BLANK5___: SimpleDropdown rozkłada na przycisku propsy zwrócone przez getToggleProps hooka useDropdown (wynik wywołania, nie samą funkcję).

  • Układanie w poziomie

    Ułóż składnię destrukturyzacji wyniku headless hooka useDropdown:

  • Klikanie w kolejności

    Kliknij w kolejności kroki tworzenia komponentu headless:

  1. PytanieDefinicja Headless Components
  2. PytanieProp getters w komponentach headless
  3. Zadanie z kodemPraktyka: headless useDropdown i useToggle
  4. Ułóż w kolejnościSkładnia headless hook useDropdown
  5. PytanieHeadless Components vs zwykłe komponenty
  6. Kliknij w kolejnościEtapy tworzenia headless component

Przydatne artykuły