Lucide, zestaw ikon SVG dla wielu frameworków

Lucide, zestaw ikon SVG dla wielu frameworków

Lucide to otwarty zestaw ikon rysowanych jedną kreską, wydawany jako osobne pakiety dla Reacta, Vue, Svelte, Solid, Angulara i czystego JavaScriptu. Wersja 1.33.0 pakietu lucide-react ukazała się w rejestrze npm 19 sierpnia 2026 roku na licencji ISC i zawiera 1776 ikon. Poniżej opisuję, co z tego wynika w praktyce, wraz z rzeczami, które dokumentacja pomija.

Co dostają pakiety Lucide

Każda ikona to komponent renderujący element svg wprost w drzewie dokumentu. Nie ma tu sprite'a, fontu ikonowego ani żądania sieciowego po dane. Atrybuty domyślne siedzą w jednym module i wyglądają tak: xmlns ustawione na przestrzeń nazw SVG, width i height równe 24, viewBox równy 0 0 24 24, fill ustawione na none, stroke ustawione na currentColor oraz strokeWidth równe 2, strokeLinecap i strokeLinejoin ustawione na round.

Wartość currentColor przy atrybucie stroke jest tu najważniejszą decyzją projektową. Ikona dziedziczy kolor tekstu rodzica, więc klasa text-red-500 z Tailwind CSS pomaluje ikonę bez żadnego dodatkowego kodu, a tryb ciemny działa sam z siebie, o ile kolor tekstu jest ustawiony na poziomie kontenera.

Rodzina pakietów w wersji 1.33.0 z 19 sierpnia 2026 roku obejmuje lucide dla czystego JavaScriptu, lucide-react dla Reacta, @lucide/vue, @lucide/svelte, lucide-solid, @lucide/angular oraz lucide-static z plikami SVG i fontem. Wszystkie deklarują licencję ISC. Zakresy zależności równorzędnych są rozłączne i nie kolidują ze sobą, bo każdy pakiet wskazuje wyłącznie swój framework: lucide-react przyjmuje React w zakresie ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0, @lucide/angular wymaga @angular/core i @angular/common w wersji co najmniej 17, lucide-solid wymaga solid-js w zakresie ^1.4.7, a @lucide/svelte przyjmuje wyłącznie Svelte 5. Pakiety Lucide nie zależą od siebie nawzajem, więc instalacja dwóch naraz nie kończy się konfliktem wersji.

Osobno rozwijany jest @lucide/lab w wersji 0.2.0 z 31 lipca 2026 roku. To poczekalnia dla ikon, które nie weszły do zestawu głównego, i numeracja poniżej jedynki jest tu uczciwym sygnałem: te ikony mogą zniknąć albo zmienić kształt.

Czego w Lucide nie ma. Nie ma ikon marek i logo, bo usunięto je w wersji 1. Nie ma wariantu wypełnionego, co potwierdza dokumentacja: strona o wypełnieniach zaczyna się zdaniem, że wypełnienia nie są oficjalnie wspierane, i pokazuje obejście polegające na podaniu fill razem z strokeWidth={0} na ikonach Star i StarHalf. Działa to na części ikon i nie działa na reszcie, bo kształty nie były rysowane z myślą o zamkniętych konturach.

# instalacja dla Reacta, z przypięciem dokładnej wersji
npm install lucide-react@1.33.0

# wariant dla czystego JavaScriptu
npm install lucide@1.33.0

# same pliki SVG i font, bez warstwy komponentów
npm install lucide-static@1.33.0

Licencja ISC i ślad po Feather

Lucide powstało jako rozwidlenie projektu Feather, który był na licencji MIT. Deklaracja w rejestrze npm mówi krótko ISC i tyle widzi większość skanerów zależności. Plik licencyjny w repozytorium mówi więcej.

W katalogu głównym lucide-icons/lucide leży plik LICENSE, bez wariantu LICENSE.md, i ma 43 linie oraz 3208 bajtów. Zaczyna się od pełnego tekstu ISC z notą o prawach autorskich w brzmieniu „Copyright (c) 2026 Lucide Icons and Contributors”. Potem następuje separator i zdanie o tym, że wymienione dalej ikony pochodzą z projektu Feather. Lista liczy dokładnie 115 nazw, od airplay po zoom-out, a pod nią stoi pełny tekst MIT z notą „Copyright (c) 2013-present Cole Bemis”, czyli autora Feather.

Trzecie źródło, czyli zawartość opublikowanej paczki, zgadza się z repozytorium co do bajta. Rozpakowany tarball lucide-react w wersji 1.33.0 zawiera plik LICENSE identyczny z tym z gałęzi głównej, a skrypt budujący w package.json robi dokładnie cp ../../LICENSE ./LICENSE, więc nie ma tu miejsca na rozjazd. Każdy plik w katalogu dist zaczyna się dodatkowo nagłówkiem @license lucide-react v1.33.0 - ISC.

Co to znaczy dla kogoś, kto wypełnia zestawienie licencji w projekcie komercyjnym. ISC i MIT są funkcjonalnie równoważne i obie wymagają zachowania noty o prawach autorskich w dystrybucji. Różnica polega na tym, że w zestawieniu trzeba wpisać dwie noty, nie jedną: Lucide Icons and Contributors dla całości oraz Cole Bemis dla tych 115 ikon. Automatyczny skaner czytający pole license z rejestru npm zobaczy tylko ISC i notę Feather po prostu zgubi. Jeżeli firma wymaga dołączania pełnych tekstów licencji do wydania, wystarczy dołączyć plik LICENSE w całości, bo obie noty są w nim razem.

Jest jeszcze drobna pułapka w samej liście. Nazwy Feather zapisano w wersji historycznej, więc znajdziesz tam alert-circle, alert-triangle czy more-horizontal, podczas gdy w bieżącym Lucide te ikony noszą inne nazwy główne i istnieją już tylko jako aliasy. Lista dotyczy pochodzenia kształtu, nie bieżącej nazwy importu, i próba automatycznego dopasowania jej do nazw komponentów użytych w kodzie da fałszywe wyniki w obie strony.

Wersja 1.0 i to, co z niej wypadło

Do marca 2026 roku numeracja szła jako 0.x, gdzie każda kolejna liczba po kropce oznaczała nowe ikony, a ostatnie wydanie z tej serii to 0.544.0 z 11 września 2025 roku. Wersja 1.0.0 trafiła do npm 23 marca 2026 roku, ale nota do wydania na GitHubie zaczyna się ostrzeżeniem, że opublikowano je przypadkowo i należy użyć 1.0.1. Poprawka wyszła tego samego dnia, około godziny później, i to ona niesie właściwą notę wydania.

Zmiany łamiące zgodność w wersji 1 są konkretne. Usunięto ikony marek, a nota migracyjna wymienia czternaście nazw: Chromium, Codepen, Codesandbox, Dribbble, Facebook, Figma, Framer, Github, Gitlab, Instagram, LinkedIn, Pocket, RailSymbol oraz Slack. Dokumentacja odsyła po zamienniki do oficjalnych materiałów marek albo do zbioru Simple Icons. Usunięto też budowanie w formacie UMD dla wszystkich pakietów poza lucide, więc zostały ESM i CJS. Atrybut aria-hidden ustawiany jest teraz domyślnie. Pakiet lucide-vue-next zmienił nazwę na @lucide/vue, a Angular dostał nową, samodzielną implementację w @lucide/angular. Dołożono dostawców kontekstu dla Reacta, Vue, Svelte i Solid, ustabilizowano punkty kodowe fontu i dodano obsługę shadow DOM w pakiecie lucide.

Skutek uboczny widać w rejestrze. Stare pakiety zamarły na progu jedynki: lucide-vue-next stoi na 1.0.0, a lucide-svelte na 1.0.1, oba z 23 marca 2026 roku. To ma znaczenie dla projektów na Svelte 3 lub 4, bo @lucide/svelte przyjmuje wyłącznie Svelte 5, a zamrożony lucide-svelte nie dostanie już nowych ikon.

Tempo wydań poza tym jest wysokie. Licząc po datach publikacji w npm, między 28 czerwca a 19 sierpnia 2026 roku ukazało się dwanaście wydań mniejszych, od 1.22.0 do 1.33.0, a łączna liczba wersji pakietu lucide-react w rejestrze przekroczyła 685. Repozytorium ma około 24,1 tysiąca gwiazdek i 1,5 tysiąca rozgałęzień, przy około 290 otwartych zgłoszeniach i 271 otwartych propozycjach zmian. Ta ostatnia liczba to głównie propozycje nowych ikon czekające na przegląd projektowy, co przy zestawie tej wielkości jest wąskim gardłem z natury rzeczy.

Rozmiar paczki, czyli najczęstsza niespodzianka

Tu leży realny problem, o którym większość tekstów o Lucide milczy. Pakiet lucide-react w wersji 1.33.0 ma po rozpakowaniu 31,4 megabajta i 4108 plików. Wersja dla czystego JavaScriptu ma 21,1 megabajta, a lucide-static aż 48,3 megabajta. Nie jest to rozmiar, który trafia do przeglądarki, ale trafia na dysk, do pamięci podręcznej menedżera pakietów i do obrazu kontenera z etapem budowania.

Struktura wygląda następująco. Katalog dist/esm/icons zawiera 2034 moduły. Z tego 1776 to ikony właściwe, 257 to moduły zachowane pod starymi nazwami dla zgodności wstecznej, a jeden, index.mjs, jest plikiem zbiorczym i nie zawiera żadnej ikony. Pojedynczy moduł jest mały: camera.mjs waży 692 bajty i eksportuje tablicę __iconNode opisującą kształty oraz gotowy komponent. Główny plik wejściowy dist/esm/lucide-react.mjs to 1791 linii samych reeksportów, a pole sideEffects w package.json jest ustawione na false. Przy budowaniu ESM z działającym usuwaniem martwego kodu import trzech ikon kończy się trzema modułami w wyniku i to jest ścieżka, którą Lucide poleca.

Kłopot zaczyna się poza tą ścieżką. Wariant CJS to jeden plik dist/cjs/lucide-react.js o rozmiarze 978 743 bajtów, w którym wszystkie 1776 ikon leży wpisanych na sztywno. Nie ma osobnych modułów CJS na ikonę. Każde środowisko, które sięgnie po pole main, czyli stary Jest bez transformacji ESM, część konfiguracji renderowania po stronie serwera i narzędzia analizujące zależności, wczyta pełne 956 kilobajtów, żeby dostać jedną strzałkę. Do tego package.json nie ma w ogóle pola exports, więc głębokie importy w rodzaju lucide-react/dist/esm/icons/camera.mjs technicznie działają, ale opierają się na układzie katalogów, którego nikt nie obiecał utrzymać między wydaniami.

Druga niespodzianka dotyczy typów. Plik dist/lucide-react.d.ts waży 2 293 869 bajtów, a obok leżą jego dwa warianty, lucide-react.prefixed.d.ts i lucide-react.suffixed.d.ts, każdy po około 2,2 megabajta. Objętość bierze się stąd, że przy każdej ikonie stoi komentarz JSDoc z podglądem w postaci obrazu SVG zakodowanego w base64. Wygoda w edytorze jest realna, koszt też: serwer języka TypeScript musi to przetrawić przy każdym otwarciu projektu.

Wersja przeglądarkowa z sieci CDN nie ma żadnego usuwania martwego kodu. Plik dist/umd/lucide.min.js z pakietu lucide waży 419 264 bajty, czyli około 97 kilobajtów po kompresji gzip, i zawiera komplet ikon. Sama dokumentacja pakietu dla czystego JavaScriptu opatruje wywołanie createIcons({ icons }) komentarzem ostrzegającym, że to zaimportuje i zbunduluje wszystkie ikony.

// zalecany import statyczny, jedna ikona to jeden moduł w wyniku budowania
import { Camera, ChevronRight } from 'lucide-react'

export function Toolbar() {
  return (
    <div className="text-slate-600">
      <Camera size={20} strokeWidth={1.5} />
      <ChevronRight size={20} absoluteStrokeWidth />
    </div>
  )
}

Jeżeli nazwa ikony pochodzi z bazy danych albo z systemu zarządzania treścią, jest na to DynamicIcon, ale dokumentacja wprost odradza go do zastosowań statycznych i wylicza cztery koszty: wszystkie ikony są importowane na etapie budowania, co wydłuża budowanie; bundler tworzy osobny moduł na ikonę, co zwiększa liczbę żądań sieciowych; przy ładowaniu widać mignięcie; a przy renderowaniu po stronie serwera trzeba zadbać, żeby ikona była dostępna przy pierwszym renderze.

// dynamiczny wybór ikony po nazwie, wraz z komponentem zastępczym
import { DynamicIcon, iconNames } from 'lucide-react/dynamic'
import { LucideProvider } from 'lucide-react'

const Placeholder = () => <span className="block h-6 w-6 rounded bg-slate-200" />

export function CmsIcon({ name }) {
  const safeName = iconNames.includes(name) ? name : 'circle-help'
  return (
    <LucideProvider size={24} strokeWidth={2} color="currentColor">
      <DynamicIcon name={safeName} fallback={Placeholder} />
    </LucideProvider>
  )
}

Atrybuty ikony i kontekst

Komponent przyjmuje color, size, strokeWidth, absoluteStrokeWidth i className, a poza tym przepuszcza dowolne atrybuty SVG dalej do elementu. Typ LucideProps rozszerza atrybuty SVG o dwa własne pola: size typu string | number oraz absoluteStrokeWidth typu boolean.

absoluteStrokeWidth rozwiązuje konkretny problem. Domyślnie grubość kreski jest podana w jednostkach układu współrzędnych ikony, więc skalując ikonę do 48 pikseli podwajasz też grubość kreski. Po ustawieniu tej flagi komponent liczy grubość według wzoru strokeWidth * 24 / size, dzięki czemu kreska ma stałą grubość niezależnie od rozmiaru. Przy ikonach ustawianych obok tekstu o różnych stopniach pisma to jest różnica widoczna gołym okiem.

Kontekst wprowadzony w wersji 1 pozwala ustawić te wartości raz dla poddrzewa. LucideProvider przyjmuje size, color, strokeWidth, absoluteStrokeWidth i className, a każdy z nich można nadpisać na pojedynczej ikonie, bo wartość z propsa ma pierwszeństwo przed wartością z kontekstu. Hook useLucideContext jest wyeksportowany, gdyby trzeba było odczytać te ustawienia we własnym komponencie.

Dostępność załatwiono rozsądnie. Komponent sprawdza, czy wśród przekazanych propsów jest cokolwiek zaczynające się od aria-, albo role, albo title. Jeżeli nic takiego nie ma i ikona nie ma dzieci, dokłada aria-hidden="true". Ikona dekoracyjna znika więc z drzewa dostępności bez żadnej pracy z twojej strony, a ikona niosąca znaczenie wymaga jawnego podania aria-label, co jest właściwą kolejnością zachęt.

Na koniec klasy CSS. Element dostaje zawsze klasę lucide, klasę z kontekstu, klasę przekazaną w className oraz klasę z nazwą ikony w postaci lucide-camera. To wygodne do stylowania globalnego, ale przy Tailwind CSS trzeba pamiętać, że własne klasy dopisywane są przed klasami użytkownika i kolejność w atrybucie nie decyduje o specyficzności.

Nazwy, aliasy i szum w podpowiedziach edytora

Główny plik wejściowy eksportuje 6092 różne nazwy dla 1776 ikon, czyli około trzech i pół nazwy na ikonę. Bierze się to z trzech stylów zapisu plus aliasów historycznych. Ikona domu jest dostępna jako House, HouseIcon i LucideHouse, a dodatkowo stara nazwa Home prowadzi do tego samego modułu. Podobnie edit-2 przemianowano na pen, a sort-desc żyje dalej jako alias arrow-down-wide-narrow.

Efekt uboczny widać przy pierwszym naciśnięciu klawisza w edytorze: automatyczne uzupełnianie zasypuje listę wariantami tej samej ikony. Dokumentacja proponuje dwa kroki. Pierwszy to wyłączenie automatycznego importu z tego pakietu przez ustawienie js/ts.preferences.autoImportFileExcludePatterns w pliku .vscode/settings.json. Drugi to własny plik deklaracji, który przekierowuje moduł na wariant z jednym stylem nazw.

// lucide-react.d.ts, zwykle w katalogu @types projektu
declare module 'lucide-react' {
  // wariant z przyrostkiem: HouseIcon, CameraIcon, ChevronRightIcon
  export * from 'lucide-react/dist/lucide-react.suffixed'
  // alternatywnie wariant z przedrostkiem:
  // export * from 'lucide-react/dist/lucide-react.prefixed'
}

Osobna sprawa to niejednoznaczność samych nazw przy zestawie tej wielkości. Przy 1776 ikonach trudno zgadnąć, czy szukany kształt nazywa się file-text, notebook-text czy scroll-text, a każdy z nich istnieje i wygląda inaczej. Publiczne API strony projektu pod adresem lucide.dev/api/tags zwraca mapę nazwa ikony na listę słów kluczowych i zawiera dokładnie 1776 pozycji, co zgadza się z zawartością paczki. To najszybszy sposób na zbudowanie własnej wyszukiwarki albo na sprawdzenie w skrypcie, czy nazwa użyta w treści redakcyjnej faktycznie istnieje.

// czysty JavaScript: importuj tylko potrzebne ikony, nie cały obiekt icons
import { createIcons, Menu, ArrowRight, Globe } from 'lucide'

createIcons({
  icons: {
    Menu,
    ArrowRight,
    Globe
  }
})

Lucide obok Iconify, Heroicons i Radix Icons

Różnica jest przede wszystkim w modelu dystrybucji, nie w liczbie ikon. Lucide daje pakiet na framework i komponent na ikonę, przez co paczka jest ogromna, a wynik budowania mały. Iconify odwraca ten układ: jeden mały komponent uniwersalny pobiera dane ikon z API albo z osobnych pakietów zestawów, dzięki czemu masz dostęp do wielu zestawów przez jeden interfejs, ale wprowadzasz zależność od źródła danych w czasie działania albo dodatkowy krok konfiguracji dla trybu offline.

Heroicons ma około 325 ikon w wariancie 24 outline i tyle samo w 24 solid, więc daje to, czego Lucide nie ma: gotowy wariant wypełniony. Cena to znacznie mniejszy zestaw. Radix Icons celuje w interfejsy o gęstym układzie, rysuje na siatce 15 na 15 i ma 318 ikon, ale ostatnie wydanie pochodzi z listopada 2024 roku, więc przy wyborze warto to potraktować jako zestaw zamknięty, a nie rozwijany. Jeśli używasz reszty rodziny Radix UI, spójność wizualna przemawia za nim mimo to.

Popularność Lucide w dużej mierze bierze się z jednej decyzji cudzego projektu. Komponenty generowane przez shadcn/ui importują ikony wprost z lucide-react: accordion sięga po ChevronDown, dialog po X, a select po Check, ChevronDown i ChevronUp. Warto przy tym zauważyć, że pole dependencies w opisie tych składników w rejestrze shadcn wymienia tylko odpowiedni pakiet Radix, więc lucide-react musi być już obecny w projekcie. Ta sama zależność ciągnie się dalej przez biblioteki budowane na tym fundamencie, w tym Magic UI, podczas gdy HeroUI idzie własną drogą i nie narzuca tego zestawu.

Zupełnie inne podejście proponuje Iconify: zamiast jednego zestawu daje jeden interfejs do 236 zestawów i ponad trzystu tysięcy ikon, więc znajdziesz tam także wariant wypełniony i ikony marek, których w Lucide nie ma. Dwie rzeczy trzeba jednak wziąć pod uwagę. Domyślny tryb komponentu pobiera dane ikon z publicznego serwera dostawcy, co oznacza zapytanie do cudzej infrastruktury przy każdym wyświetleniu i brak jakiejkolwiek umowy o dostępności. Druga to licencje: zestawy mają własne warunki, dwa z nich zakazują użycia komercyjnego, a sześć jest na licencjach z rodziny GPL, więc audyt trzeba zrobić per zestaw, nie raz dla całości.

Typowe błędy

Import całego obiektu icons w pakiecie dla czystego JavaScriptu i wywołanie createIcons({ icons }). To wciąga komplet ikon do wyniku budowania i jest jedynym miejscem, w którym dokumentacja sama stawia ostrzeżenie w kodzie przykładowym.

Poleganie na tym, że dowolny bundler usunie martwy kod. Usuwanie działa dla ESM, gdzie każda ikona jest osobnym modułem, a nie dla ścieżki CJS, gdzie wszystko leży w jednym pliku o rozmiarze 956 kilobajtów. Jeśli w konfiguracji testów albo w kroku renderowania po stronie serwera coś sięga po pole main, sprawdź, co realnie zostało wczytane.

Głębokie importy w rodzaju lucide-react/dist/esm/icons/camera.mjs w nadziei na mniejszy wynik. Pakiet nie ma pola exports, więc taka ścieżka działa przypadkiem, a nie na mocy umowy, i może zniknąć przy zmianie konfiguracji budowania po stronie Lucide.

Ustawianie rozmiaru ikony przez width i height w CSS przy jednoczesnym pozostawieniu strokeWidth bez zmian. Kreska skaluje się razem z ikoną, przez co ikona 48 pikseli wygląda na grubszą niż otaczający ją tekst. Właściwym rozwiązaniem jest absoluteStrokeWidth.

Zakładanie, że ikony marek nadal są w zestawie. W kodzie sprzed wersji 1 importy takie jak Github czy Figma działały, po aktualizacji do jedynki przestają się kompilować i trzeba je zastąpić własnym SVG albo innym zestawem.

Wpisanie do zestawienia licencji samego ISC na podstawie pola z rejestru npm. Nota MIT dla 115 ikon odziedziczonych po Feather jest w tym samym pliku licencyjnym i skaner czytający wyłącznie metadane pakietu jej nie zobaczy.

FAQ

Ile ikon ma Lucide w wersji 1.33.0

Dokładnie 1776. Tyle modułów ikon jest reeksportowanych z głównego pliku wejściowego pakietu lucide-react i tyle pozycji zwraca publiczne API strony projektu pod adresem lucide.dev/api/tags. W katalogu dist/esm/icons leżą jednak 2034 moduły, bo 257 z nich to stare nazwy zachowane dla zgodności wstecznej, a jeden to plik zbiorczy index.mjs.

Czy Lucide ma wariant wypełniony

Nie. Dokumentacja stwierdza wprost, że wypełnienia nie są oficjalnie wspierane, i pokazuje obejście z atrybutem fill oraz strokeWidth={0} na przykładzie ikon Star i StarHalf. Działa to na ikonach, których kontury są zamknięte, i nie działa na pozostałych. Jeśli wariant wypełniony jest wymogiem projektu, Heroicons daje go w komplecie.

Czy licencja ISC wystarczy w projekcie komercyjnym

Tak, ISC jest licencją permisywną i pozwala na użycie komercyjne, wymaga jedynie zachowania noty o prawach autorskich. Trzeba jednak przenieść do zestawienia obie noty z pliku LICENSE, czyli ISC dla całości oraz MIT z prawami Cole'a Bemisa dla 115 ikon pochodzących z Feather. Najprościej dołączyć ten plik w całości.

Dlaczego paczka waży 31 megabajtów, skoro Lucide reklamuje się usuwaniem martwego kodu

Bo to dwie różne rzeczy. Na dysku leży komplet 1776 ikon w trzech postaciach, ESM, CJS i deklaracje typów, przy czym same pliki .d.ts zajmują ponad 6,6 megabajta z powodu podglądów SVG w komentarzach. Do przeglądarki trafiają tylko ikony faktycznie zaimportowane, o ile budujesz przez ESM.

Który pakiet wybrać dla Svelte

Dla Svelte 5 jest @lucide/svelte w wersji 1.33.0. Dla Svelte 3 i 4 pozostaje lucide-svelte, ale ten pakiet stoi na 1.0.1 z 23 marca 2026 roku i nowych ikon już nie dostanie. Analogicznie w Vue nazwą bieżącą jest @lucide/vue, a lucide-vue-next zamarł na 1.0.0.

Czy da się używać Lucide bez menedżera pakietów

Da się, przez plik UMD z sieci CDN, ale bez usuwania martwego kodu. Plik dist/umd/lucide.min.js waży 419 264 bajty, czyli około 97 kilobajtów po kompresji, i zawiera wszystkie ikony. Dokumentacja odradza wskazywanie na @latest i zaleca przypięcie dokładnej wersji w adresie.