HeroUI, biblioteka komponentów React

HeroUI, biblioteka komponentów React

HeroUI to biblioteka gotowych komponentów dla Reacta, która przez pierwsze lata nazywała się NextUI. Zmieniła nie tylko nazwę, ale w wersji trzeciej także fundamenty, na których stoi. Jeśli trafiłeś na starszy poradnik, prawie na pewno opisuje on coś, co dziś już nie działa.

Skąd wzięła się zmiana nazwy

Projekt powstał jako NextUI i pod tą nazwą zebrał większość swojej popularności. Nazwa okazała się jednak problemem, bo ludzie masowo brali go za oficjalną bibliotekę komponentów Next.js, czym nigdy nie był. Działa z Next.js równie dobrze jak z każdym innym sposobem uruchamiania Reacta, a powiązanie sugerowane przez nazwę było czystym nieporozumieniem.

Stąd zmiana na HeroUI. Stary pakiet @nextui-org/react zatrzymał się na wersji 2.6.11 wydanej w styczniu 2025 roku i nie dostaje już poprawek. Cały rozwój przeniósł się do @heroui/react, więc jeśli w projekcie masz jeszcze stary identyfikator pakietu, to nie jest kwestia estetyki, tylko brak dostępu do wszystkiego, co powstało od tamtej pory.

Repozytorium heroui-inc/heroui ma dziś ponad trzydzieści tysięcy gwiazdek, a sama biblioteka jest całkowicie darmowa, bez wariantu płatnego i bez ograniczeń użycia komercyjnego. Z nazwą licencji wiąże się jednak niejasność, o której warto wiedzieć przed audytem zależności. Plik licencji w repozytorium oraz metadane pakietu w rejestrze npm deklarują MIT, ale paczka opublikowana dla wersji trzeciej niesie w środku tekst Apache 2.0. Paczki z linii drugiej mają w środku MIT, zgodnie z resztą. Interfejs GitHuba też pokazuje Apache 2.0, więc jedynym miejscem, w którym widać rzeczywisty stan, jest zawartość pobranej paczki. Obie licencje są permisywne i żadna nie blokuje użycia komercyjnego, więc różnica boli głównie tam, gdzie ktoś zestawia listę licencji zależności i oczekuje jednej odpowiedzi.

Co naprawdę zmieniła wersja trzecia

To najważniejsza część tego tekstu, bo różnica między dwójką a trójką nie jest kosmetyczna. Zmieniły się zależności, wymagania i sposób konfiguracji, a większość materiałów krążących po sieci opisuje wciąż stan sprzed tej zmiany.

Wersja druga była zbiorem kilkudziesięciu osobnych pakietów. Pakiet zbiorczy @heroui/react zaciągał @heroui/button, @heroui/card, @heroui/modal i tak dalej, a każdy z nich można było zainstalować pojedynczo, żeby zmniejszyć rozmiar paczki wynikowej. Ostatnie wydanie tej linii nosi numer 2.8.10 i pochodzi z marca 2026 roku.

Wersja trzecia zwinęła to wszystko do jednego pakietu. Dzisiejsze @heroui/react ma raptem kilka zależności: własny pakiet ze stylami, bibliotekę wariantów klas, jeden prymityw do awatara i kilka drobiazgów. Pojedyncze pakiety komponentów zostały tam, gdzie były, zamrożone na wersjach z linii drugiej. Instrukcja mówiąca „zainstaluj tylko @heroui/button" ściągnie Ci więc do projektu kod sprzed roku, mimo że pakiet nadal istnieje w rejestrze i instaluje się bez najmniejszego protestu.

Zmieniły się też wymagania wobec otoczenia, i to znacząco. Wersja trzecia deklaruje Reacta w wersji co najmniej dziewiętnastej, Tailwind CSS w wersji co najmniej czwartej oraz React Aria Components. Wersja druga zadowalała się Reactem osiemnastym i Tailwindem trzecim. To nie jest różnica, którą przeskakuje się podniesieniem jednej linijki w pliku z zależnościami.

Najbardziej zaskakujący jest zanik biblioteki animacji. Wersja druga wymagała Framer Motion jako zależności równorzędnej i praktycznie każdy poradnik zaczyna się od instalowania jej obok HeroUI. W wersji trzeciej nie ma jej w wymaganiach w ogóle. Polecenie instalacji przepisane ze starszego artykułu doda Ci więc do projektu sporą bibliotekę, po którą nic nie sięga.

Na czym to stoi

Warto rozumieć, co jest pod spodem, bo to wyjaśnia zarówno mocne strony biblioteki, jak i jej ograniczenia.

Warstwa zachowania pochodzi z React Aria Components, czyli z zestawu przygotowanego przez zespół projektujący systemy interfejsów w Adobe. To jest ten fragment, który odpowiada za obsługę klawiatury, zarządzanie ogniskiem, komunikaty dla czytników ekranu i poprawne zachowanie przy różnych metodach wprowadzania danych. Napisanie tego samodzielnie i doprowadzenie do stanu zgodnego z wytycznymi dostępności to praca na miesiące, więc oparcie się na gotowej warstwie jest tu największą wartością.

Warstwa wizualna to Tailwind. Style opisano przez warianty klas, a nie przez arkusze przypisane do komponentów, dzięki czemu nadpisanie wyglądu sprowadza się do dopisania klas w miejscu użycia. Jeśli w projekcie i tak korzystasz z Tailwind CSS, biblioteka wpina się bez osobnego systemu stylowania i bez drugiego zestawu zmiennych do utrzymania.

Ta konstrukcja tłumaczy też, gdzie HeroUI leży na mapie bibliotek. Nie jest zestawem samych prymitywów bez wyglądu, jak Radix UI czy Headless UI, bo dostajesz gotowy, dopracowany wygląd. Nie jest też zbiorem plików do skopiowania do repozytorium, jak shadcn/ui, bo instalujesz zależność i aktualizujesz ją jak każdą inną. Ten wybór ma konsekwencje w obie strony: aktualizacja przychodzi sama, ale zmiana czegoś, czego biblioteka nie przewidziała, wymaga obejścia zamiast edycji pliku.

Porównanie z alternatywami

Trzy kryteria wystarczą, żeby ustawić te biblioteki obok siebie: sposób dostarczania kodu, to skąd bierze się wygląd, i to skąd bierze się zachowanie.

Wniosek z tej tabeli jest prostszy, niż się wydaje. Jeśli chcesz gotowy wygląd i aktualizacje przychodzące same, zostają HeroUI i Mantine, a wybór między nimi sprowadza się do tego, czy stylujesz Tailwindem, czy wolisz osobny system stylów. Jeśli chcesz gotowy wygląd, ale z możliwością wejścia w każdy plik, wybierasz shadcn/ui i przyjmujesz, że aktualizacje robisz ręcznie. Jeśli masz własny system projektowy, bierzesz prymitywy i nie płacisz za warstwę, którą i tak byś nadpisał.

Jak wygląda migracja z wersji drugiej

Jeśli decydujesz się na przejście, kolejność ma znaczenie, bo próba zrobienia wszystkiego naraz kończy się zwykle błędami, których nie da się przypisać do żadnej konkretnej zmiany.

Zacznij od Reacta. Podniesienie do dziewiętnastki jest niezależne od tej biblioteki i warto je odseparować, żeby ewentualne problemy z innymi zależnościami wyszły osobno. Dopiero potem bierz się za Tailwinda, bo przejście z trójki na czwórkę zmienia sposób konfiguracji całego projektu, a nie tylko komponentów.

Kiedy oba fundamenty stoją, zamień pakiet i usuń z zależności wszystko, co było potrzebne wyłącznie starej wersji: pojedyncze pakiety komponentów, pakiet z motywem i bibliotekę animacji. Ten krok jest zwykle przyjemniejszy niż się wydaje, bo z pliku zależności znika kilkanaście wpisów.

Na końcu przejrzyj miejsca, w których nadpisywałeś wygląd przez konfigurację motywu. To jest ta część, która nie przeniesie się sama i wymaga przepisania na nowy sposób konfiguracji. Nadpisania robione klasami w miejscu użycia przetrwają migrację bez zmian, więc im więcej robiłeś w ten sposób, tym mniej pracy zostaje.

Instalacja i pierwsze uruchomienie

W wersji trzeciej instalacja to jedno polecenie.

npm install @heroui/react

Zanim je wywołasz, sprawdź trzy rzeczy, bo każda z nich potrafi zatrzymać projekt na etapie budowania. React musi być w wersji dziewiętnastej lub nowszej. Tailwind CSS musi być w wersji czwartej lub nowszej. Musi też być dostępny React Aria Components, który biblioteka deklaruje jako zależność równorzędną, więc menedżer pakietów zgłosi brak, jeśli go nie ma.

Wersje sprawdzisz szybciej niż przez przeglądanie pliku z zależnościami.

npm ls react tailwindcss react-aria-components

Jeśli projekt siedzi na Reakcie osiemnastym albo Tailwindzie trzecim, masz dwie drogi. Pierwsza to podniesienie obu i przejście na wersję trzecią. Druga to pozostanie przy wersji drugiej, przypiętej jawnie w pliku z zależnościami, ze świadomością, że ta linia dostała ostatnie wydanie w marcu 2026 roku i nowe komponenty już się w niej nie pojawią.

{
  "dependencies": {
    "@heroui/react": "^2.8.10"
  }
}

Przy nowym projekcie ta decyzja właściwie nie istnieje, bo wszystko powyżej i tak zaczynasz od najnowszych wersji. Problem dotyczy wyłącznie kodu, który już działa i ma swoje zależności ustalone od dawna.

Konfiguracja motywów

Tu również zaszła zmiana warta uwagi, wynikająca wprost z przejścia na Tailwind w wersji czwartej.

W wersji drugiej motyw konfigurowało się w pliku konfiguracyjnym Tailwinda, przez wtyczkę dołączaną w tablicy wtyczek, z kolorami opisanymi jako obiekt JavaScriptu. Tailwind czwarty przeniósł konfigurację do arkusza stylów, więc i tutaj punkt ciężkości przesunął się z pliku konfiguracyjnego do pliku CSS. Osobny pakiet ze stylami dostarcza warstwę bazową, warianty i motywy jako gotowe arkusze do zaimportowania.

Praktyczny wniosek jest taki, że przykład konfiguracji znaleziony w starszym poradniku, z wtyczką w pliku konfiguracyjnym i obiektem kolorów, w wersji trzeciej po prostu nie zadziała. Aktualną postać sprawdź w dokumentacji, bo akurat ta rzecz zmieniała się między wydaniami częściej niż cokolwiek innego.

Sam mechanizm nadpisywania wyglądu pozostał ten sam i jest jedną z lepszych stron biblioteki. Komponenty przyjmują klasy Tailwinda w miejscu użycia i scalają je z klasami własnymi, rozstrzygając konflikty na korzyść Twoich. Nie musisz więc walczyć ze specyficznością selektorów ani sięgać po wykrzyknik w stylach, żeby zmienić jeden odstęp.

W najprostszej postaci wygląda to jak zwykła właściwość z klasami.

<Button className="bg-purple-500 hover:bg-purple-600">
  Zapisz
</Button>

Ciekawsza jest druga postać, w której zamiast łańcucha znaków podajesz funkcję otrzymującą stan komponentu. Pozwala to opisać wygląd dla stanu wciśnięcia albo najechania bez sięgania po własny stan w Reakcie.

<Button
  className={({ isPressed }) =>
    isPressed ? 'bg-blue-600' : 'bg-blue-500'
  }
>
  Wyślij
</Button>

Ten drugi wariant warto znać, zanim zaczniesz obudowywać komponent własnym stanem. Sporo kodu pisanego wokół takich bibliotek powstaje wyłącznie dlatego, że autor nie wiedział o dostępie do stanu wewnętrznego w miejscu stylowania.

Kiedy warto, a kiedy lepiej nie

Warto, jeśli projekt stoi na Tailwindzie i chcesz gotowy, spójny wygląd bez budowania własnego systemu projektowego. To najczęstszy sensowny scenariusz. Dostajesz komplet komponentów wyglądających jak jedna całość i oszczędzasz tygodnie pracy nad rzeczami, których użytkownik i tak nie zauważy, dopóki nie są zepsute.

Warto też, jeśli dostępność jest wymogiem, a nie deklaracją. Warstwa zachowania z React Aria załatwia obsługę klawiatury i czytników ekranu na poziomie, którego samodzielnie nie osiągniesz przy rozsądnym nakładzie pracy. Przy zamówieniach publicznych i produktach dla większych organizacji to bywa argument rozstrzygający.

Nie warto, jeśli masz już własny system projektowy z ustalonymi komponentami. Wtedy gotowy wygląd jest przeszkodą, a nie zaletą, i lepiej sięgnąć po same prymitywy bez stylów, żeby nie płacić za warstwę, którą i tak trzeba nadpisać w całości.

Nie warto również, jeśli projekt nie może przejść na Reacta dziewiętnastego i Tailwinda czwartego. Instalowanie w takiej sytuacji wersji drugiej działa, ale wiążesz się z linią, która już nie jest rozwijana, i za jakiś czas i tak staniesz przed tą samą migracją, tylko z większą ilością kodu do przeniesienia.

Ostatni przypadek jest mniej oczywisty. Jeśli potrzebujesz dwóch albo trzech komponentów, cała biblioteka to nadmiar. Kiedyś ratowały tu pojedyncze pakiety, ale w wersji trzeciej ich nie ma, więc przy tak wąskiej potrzebie rozsądniej wziąć pojedynczy prymityw albo skopiować gotowy komponent do repozytorium.

Typowe błędy

Pierwszy to instalowanie Framer Motion razem z biblioteką, bo tak każe starszy poradnik. W wersji trzeciej to zależność zbędna, dokładająca do paczki wynikowej kod, po który nic nie sięga.

Drugi to sięganie po pojedyncze pakiety komponentów. Wyglądają na wciąż aktualne, bo istnieją w rejestrze i instalują się bez błędu, ale zawierają kod z linii drugiej, a wymieszanie ich z pakietem zbiorczym w wersji trzeciej kończy się dwiema wersjami stylów w jednym projekcie i wyglądem, którego nikt nie zaprojektował.

Trzeci to przenoszenie konfiguracji motywu z pliku konfiguracyjnego Tailwinda bez zmian. Po przejściu na Tailwinda czwartego ta forma konfiguracji nie jest już rozpoznawana, a efektem jest komplet komponentów w kolorach domyślnych i wrażenie, że motyw został zignorowany, bo faktycznie został.

Czwarty to pozostawienie w projekcie starego identyfikatora pakietu. Wpis z przedrostkiem @nextui-org nadal się instaluje i nadal działa, więc nic nie zwraca na siebie uwagi, ale wskazuje na kod zamrożony na początku 2025 roku.

Piąty to zakładanie, że aktualizacja z wersji drugiej na trzecią jest zmianą numeru w pliku z zależnościami. Skoro zmieniły się wymagania wobec Reacta i Tailwinda, a warstwa stylów przeniosła się do innego pakietu, jest to migracja wymagająca zaplanowania, a nie rutynowa aktualizacja przy okazji.

FAQ

Czy HeroUI to to samo co NextUI?

Tak, to ten sam projekt po zmianie nazwy. Pakiet @nextui-org/react został zamrożony na wersji 2.6.11 ze stycznia 2025 roku, a rozwój toczy się w @heroui/react.

Czy biblioteka jest darmowa?

Tak, w całości, i nie ma wariantu płatnego ani ograniczeń użycia komercyjnego. Sama nazwa licencji bywa jednak podawana dwojako: rejestr npm i plik README mówią MIT, a plik licencji w repozytorium i w paczce z wersją trzecią to od kwietnia 2026 roku Apache 2.0. Obie są permisywne, więc dla samego użycia nic się nie zmienia.

Czy da się używać HeroUI bez Tailwinda?

Nie. Tailwind jest tu warstwą stylowania, a nie opcją do włączenia, i wersja trzecia wymaga go w wersji co najmniej czwartej.

Czy wersja trzecia wymaga Reacta dziewiętnastego?

Tak, deklaruje Reacta i React DOM w wersji co najmniej dziewiętnastej. Przy Reakcie osiemnastym zostaje wersja druga, która jednak nie jest już rozwijana.

Czy potrzebuję Framer Motion?

W wersji trzeciej nie. Wymagała go wersja druga i stąd bierze się ta informacja w starszych materiałach.

Jak sprawdzić, którą wersję mam w projekcie?

Poleceniem npm ls @heroui/react. Numer zaczynający się od dwójki oznacza starą linię z osobnymi pakietami komponentów, od trójki nową.

Kod źródłowy i wydania znajdziesz w repozytorium HeroUI, a bieżące numery wersji w rejestrze npm.