Kurs JavaScript i React · Moduł 15: Wzorce i architektura
Headless Components - Oddzielenie logiki od prezentacji
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:
- Zarządza stanem i logiką (otwieranie/zamykanie, selekcja, nawigacja)
- NIE renderuje żadnego JSX, czyli nie ma własnego wyglądu
- 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?
| Cecha | Zwykły komponent | Headless Component |
|---|---|---|
| UI | Wbudowane style/JSX | Zero, TY decydujesz |
| Reużywalność | Ograniczona do jednego wyglądu | Nieograniczona |
| Dostępność | Trzeba implementować ręcznie | Wbudowane aria-atrybuty |
| Testowalność | Wymaga renderowania | Testuj 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ą klawiaturyCombobox: autocomplete/searchDialog: modal z focus trapDisclosure: accordion/expandableMenu: dropdown menuTabs: 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. Czym są Headless Components w kontekście React?
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: