Tworzenie niestandardowego panelu ustawień dla motywu WordPress to zadanie, które potrafi rozciągnąć się na tygodnie. WordPress Settings API wymaga napisania ogromnej ilości szablonowego kodu: rejestracja, renderowanie pól, walidacja, zapisywanie. A gdy projekt płonie, pisanie tego wszystkiego od zera to nieuzasadniony luksus.

Redux Framework rozwiązuje ten problem radykalnie: zamiast ręcznej bieganiny z Settings API opisuje Pan potrzebne pola w jednym pliku konfiguracyjnym, a framework bierze na siebie całą resztę, renderowanie, walidację, eskejpowanie, import/eksport, a nawet dynamiczny CSS. Na WordPress.org wtyczka ma ponad 32 miliony pobrań i ponad milion aktywnych instalacji, i nie jest to marketingowe nabijanie liczników, lecz bezpośrednia konsekwencja tego, że Redux realnie oszczędza tygodnie pracy programistycznej.

W tym poradniku, krok po kroku skonfigurujemy Redux Framework od zera do działającego panelu opcji motywu, włącznie z demonstracją na żywo w customizerze i bezpiecznym wykorzystaniem zapisanych wartości na frontendzie.

💡 Szybki przegląd:

• Instalacja Redux Framework: trzy sposoby integracji z projektem WordPress
• Podłączenie frameworku i utworzenie pliku konfiguracyjnego
• Konfiguracja argumentów panelu: pozycja w menu, customizer, Google Fonts
• Dodawanie sekcji i pól formularza za pomocą jednolitego API Redux
• Pobieranie zapisanych wartości w szablonach motywu z zabezpieczeniem przed błędami

Czym jest Redux Framework i do czego służy

Redux Framework to darmowy, otwartoźródłowy framework opcji dla motywów i wtyczek WordPress. Zbudowany na bazie standardowego WordPress Settings API, ale całkowicie abstrahuje jego złożoność. Zamiast dziesiątek wywołań register_setting, add_settings_field i settings_fields pisze Pan deklaratywną tablicę w PHP i otrzymuje w pełni funkcjonalny, responsywny panel ustawień z 49 typami pól do wyboru.

Ważne, by nie mylić go z biblioteką JavaScript Redux do zarządzania stanem, to zupełnie różne produkty o tej samej nazwie. Framework dla WordPressa pojawił się wcześniej niż biblioteka JS.

Kluczowe możliwości, które otrzymuje Pan „od ręki":

• 49 typów pól: od zwykłego tekstu i checkboxa po edytor ACE, repeater, Google Maps, sorter bloków i slider obrazów;
• Automatyczne generowanie CSS: dla pól typografii, koloru, gradientów, odstępów wystarczy wskazać selektor CSS, a Redux sam wygeneruje arkusz stylów z Google Fonts;
• Integracja z customizerem: argument customizer => true i cały panel jest duplikowany w WordPress Customizer z podglądem na żywo;
• Import/eksport ustawień: wbudowane narzędzie do przenoszenia konfiguracji między stronami;
• Kompilator: hak uruchamiany przy zmianie pola z flagą compile => true, można na przykład przebudować SCSS;
• Walidacja i eskejpowanie: każda wartość przechodzi sanityzację odpowiadającą typowi pola, pole tekstowe nie przyjmie tablicy, numeryczne odrzuci ciągi znaków.

Od 2024 roku framework rozwija się pod skrzydłami Team Updraft (David Anderson, twórca UpdraftPlus). Aktualna wersja, 4.5.11 (marzec 2026), jest w pełni kompatybilna z WordPress 7.0 i PHP 8.5. Projekt żyje na redux.io, dokumentacja na stronie dokumentacji Redux.

Instalacja Redux Framework

Są trzy sposoby dodania Redux do projektu. Wybór zależy od architektury Pana motywu i tego, jak planuje go Pan dystrybuować.

Jako osobna wtyczka

Proszę zainstalować Redux Framework z katalogu WordPress.org jak zwykłą wtyczkę. Po aktywacji panel opcji nie pojawi się, wtyczka jedynie udostępnia API. Wszystkie ustawienia opisuje Pan w pliku konfiguracyjnym wewnątrz swojego motywu.

Zalety: motyw pozostaje lekki (rdzeń frameworku nie rozdyma archiwum); framework aktualizuje się niezależnie poprzez standardowy mechanizm WordPress.

Wady: Pana motyw wymaga obecności zewnętrznej wtyczki, użytkownik musi ją osobno zainstalować i aktywować; przy braku wtyczki panel ustawień znika i trzeba przewidzieć bezpieczny fallback w kodzie motywu.

W rdzeniu motywu

Proszę skopiować folder ReduxCore do wnętrza swojego motywu i podłączyć go w functions.php. Framework staje się integralną częścią motywu, użytkownik nie musi instalować dodatkowej wtyczki.

Zalety: panel ustawień wygląda jak natywna część motywu, użytkownik niczego dodatkowo nie instaluje.

Wady: rozmiar archiwum motywu rośnie o około 2 MB; każda aktualizacja frameworku wymaga z Pana strony aktualizacji motywu; wtyczka Theme Check może zgłaszać ostrzeżenia.

W zależnej wtyczce motywu

Rekomendowane podejście dla motywów premium. Proszę utworzyć osobną wtyczkę towarzyszącą dla swojego motywu (w niej wygodnie jest też trzymać niestandardowe typy wpisów, shortkody, widgety) i osadzić w niej Redux. W functions.php motywu proszę dodać sprawdzenie obecności tej wtyczki przez TGMPA lub analogiczny mechanizm.

Zalety: czysta architektura (funkcjonalność motywu oddzielona od warstwy prezentacji); framework nie rozdyma archiwum motywu; aktualizacje frameworku nie dotykają bezpośrednio kodu motywu.

Wady: trzeba napisać i utrzymywać osobną wtyczkę; nieco wyższy próg wejścia dla innych programistów, którzy będą się wdrażać w projekt.

Konfiguracja Redux nie zależy od sposobu instalacji, dalsze kroki są identyczne dla każdego wariantu.

Konfiguracja ogólna: podłączamy framework

Wewnątrz wtyczki Redux Framework (lub archiwum pobranego z oficjalnej strony Redux) proszę znaleźć folder ReduxCore, zawiera on cały rdzeń.

Proszę utworzyć w swojej wtyczce (lub motywie) folder, na przykład optionpanel, i skopiować do niego zawartość ReduxCore. Obok proszę umieścić pusty plik config.php, to właśnie w nim opiszemy wszystkie sekcje i pola panelu ustawień.

Teraz proszę podłączyć framework. Do głównego pliku wtyczki (lub functions.php motywu) proszę dodać:

1
<?php
2
if ( ! class_exists( 'Redux' ) ) {
3
    require_once plugin_dir_path( __FILE__ ) . 'optionpanel/ReduxCore/framework.php';
4
}

Sprawdzenie class_exists zapobiega błędowi krytycznemu, jeśli inna część witryny załadowała już Redux (na przykład przez osobny plugin). Jeśli framework jest nieobecny, panel ustawień po prostu się nie załaduje, a witryna będzie nadal działać.

Następnie można przejść do tworzenia sekcji i pól.

Tworzenie panelu opcji

Argumenty frameworku

Przede wszystkim należy zdefiniować zmienną globalną do przechowywania wszystkich ustawień, będzie ona potrzebna do pobierania wartości w szablonach motywu:

1
$opt_name = 'mytheme_options';

Prefiks jest obowiązkowy, zapobiega konfliktom nazw z innymi pluginami korzystającymi z Redux. Dobra praktyka: brandname_themename.

Teraz zbudujemy tablicę argumentów. Oto minimalna działająca konfiguracja:

1
$args = array(
2
    'opt_name'             => $opt_name,
3
    'display_name'         => 'Настройки темы',
4
    'display_version'      => '1.0.0',
5
    'menu_type'            => 'submenu',
6
    'allow_sub_menu'       => true,
7
    'menu_title'           => 'Настройки темы',
8
    'page_title'           => 'Панель настроек темы',
9
    'page_parent'          => 'themes.php',
10
    'page_permissions'     => 'manage_options',
11
    'page_slug'            => 'theme_options',
12
    'dev_mode'             => false,
13
    'update_notice'        => false,
14
    'customizer'           => true,
15
    'save_defaults'        => true,
16
    'show_import_export'   => true,
17
    'async_typography'     => true,
18
    'admin_bar'            => true,
19
    'global_variable'      => $opt_name,
20
);
21
 
22
Redux::set_args( $opt_name, $args );

Omówienie kluczowych argumentów:

• menu_type: submenu, panel pojawi się wewnątrz pozycji „Wygląd"; menu, osobna pozycja najwyższego poziomu w panelu administracyjnym;
• customizer: true włącza duplikowanie wszystkich pól w WordPress Customizer z podglądem na żywo, użytkownik widzi zmiany przed zapisaniem;
• dev_mode: należy włączyć na czas prac programistycznych (rozszerzone debugowanie, import demonstracyjny), ale koniecznie wyłączyć przed wydaniem;
• update_notice: zawsze false dla motywów i pluginów z wbudowanym Redux, Państwa użytkownicy nie powinni otrzymywać powiadomień o aktualizacji frameworku niezależnie od Państwa produktu;
• show_import_export: dodaje narzędzie do przenoszenia wszystkich ustawień między witrynami jednym kliknięciem.

Pełna lista ponad 40 argumentów znajduje się w przewodniku po argumentach.

Dodawanie sekcji i pól

Sekcja to logiczna grupa pól (zakładka na ekranie ustawień). Minimalna sekcja:

1
Redux::set_section( $opt_name, array(
2
    'title'  => 'Шапка сайта',
3
    'id'     => 'header_section',
4
    'icon'   => 'dashicons-heading',
5
    'fields' => array(
6
        array(
7
            'id'       => 'header_logo',
8
            'type'     => 'media',
9
            'title'    => 'Логотип',
10
            'subtitle' => 'Загрузите изображение логотипа',
11
            'default'  => array( 'url' => get_template_directory_uri() . '/images/logo.png' ),
12
        ),
13
        array(
14
            'id'      => 'sticky_header',
15
            'type'    => 'switch',
16
            'title'   => 'Фиксированная шапка',
17
            'default' => true,
18
        ),
19
    ),
20
) );

Ikony sekcji: Redux 4.x obsługuje wbudowane ikony WordPress Dashicons (pełna lista na developer.wordpress.org). Dla niestandardowych ikon należy użyć klas CSS z Państwa zestawu (na przykład Font Awesome).

Każde pole to tablica asocjacyjna z obowiązkowymi kluczami id, type i title. Przykłady często używanych typów:

1
// Селект с поиском
2
array(
3
    'id'      => 'sidebar_layout',
4
    'type'    => 'select',
5
    'title'   => 'Раскладка сайдбара',
6
    'options' => array(
7
        'right' => 'Сайдбар справа',
8
        'left'  => 'Сайдбар слева',
9
        'none'  => 'Без сайдбара',
10
    ),
11
    'default' => 'right',
12
),
13
 
14
// Выбор цвета RGBA
15
array(
16
    'id'      => 'accent_color',
17
    'type'    => 'color_rgba',
18
    'title'   => 'Акцентный цвет',
19
    'default' => array(
20
        'color' => '#2271b1',
21
        'alpha' => 1,
22
    ),
23
),
24
 
25
// Типографика с Google Fonts
26
array(
27
    'id'          => 'body_typography',
28
    'type'        => 'typography',
29
    'title'       => 'Шрифт текста',
30
    'google'      => true,
31
    'font-backup' => true,
32
    'line-height' => true,
33
    'font-size'   => true,
34
    'default'     => array(
35
        'font-family' => 'Inter',
36
        'font-size'   => '16px',
37
    ),
38
),

Aby utworzyć podsekcję, należy dodać argument 'subsection' => true, pole pojawi się jako zagnieżdżona zakładka wewnątrz sekcji nadrzędnej.

Lista wszystkich 49 typów z przykładami konfiguracji znajduje się w rozdziale typy pól dokumentacji Redux.

Użycie parametrów w motywie

Redux przechowuje wszystkie wartości w jednej zmiennej globalnej, tej samej, którą podali Państwo w $opt_name. Aby pobrać wartość w szablonie, należy najpierw zadeklarować ją jako globalną. Jednak bezpośrednia deklaracja global poza funkcją lub akcją to zła praktyka. Właściwe podejście:

1
function mytheme_get_option( $option_id, $default = '' ) {
2
    global $mytheme_options;
3
    return isset( $mytheme_options[ $option_id ] ) ? $mytheme_options[ $option_id ] : $default;
4
}

Funkcja opakowująca robi dwie rzeczy: zapobiega PHP Notice „undefined index" przy odwołaniu do nieistniejącego klucza oraz dostarcza wartość domyślną (fallback). W szablonie użycie wygląda następująco:

1
$logo = mytheme_get_option( 'header_logo' );
2
if ( ! empty( $logo['url'] ) ) {
3
    echo '<img src="' . esc_url( $logo['url'] ) . '" alt="' . esc_attr( get_bloginfo( 'name' ) ) . '">';
4
}

Jeśli panel ustawień nie został jeszcze skonfigurowany (na przykład użytkownik aktywował motyw, ale nie zainstalował wymaganej wtyczki), $mytheme_options będzie pustą tablicą, a mytheme_get_option() po cichu zwróci $default, bez lawiny ostrzeżeń w debug.log.

Dla dynamicznego CSS należy użyć wbudowanej możliwości Redux, podając argument output w konfiguracji pola:

1
array(
2
    'id'     => 'body_bg_color',
3
    'type'   => 'color',
4
    'title'  => 'Цвет фона',
5
    'output' => array( 'background-color' => 'body' ),
6
),

Redux automatycznie wygeneruje i osadzi regułę CSS <style>body{background-color:#fff;}</style>, bez ani jednej linii ręcznego kodu.

Proces instalacji i konfiguracji pól został pokazany krok po kroku w tym samouczku wideo: od podłączenia frameworka do utworzenia pierwszej sekcji z selektorami i przełącznikami:

⁉️🤔 Często zadawane pytania

Czym Redux Framework różni się od Carbon Fields, ACF Options Pages i innych rozwiązań?

Redux oferuje 49 typów pól „od ręki" (wobec ~25 w Carbon Fields i ~30 w ACF Pro) i koncentruje się właśnie na panelach ustawień motywu, a nie na metapolach wpisów. ACF Options Pages to nadbudowa nad silnikiem metapól, podczas gdy Redux od samego początku został zaprojektowany pod panele opcji: wbudowany import/eksport, kompilator, podgląd na żywo w customizerze, dynamiczny CSS z Google Fonts. Carbon Fields jest bliższy duchem, ale wymaga Composera i przestrzeni nazw, co w wielu środowiskach hostingowych stanowi barierę. Wniosek: jeśli używają już Państwo ACF do metapól, proszę sięgnąć po ACF Options Pages, aby nie mnożyć bytów; jeśli budują Państwo motyw od zera i potrzebny jest potężny panel opcji, Redux da więcej możliwości za darmo.

Czy Redux Framework działa z motywami blokowymi (Full Site Editing)?

Tak, ale z zastrzeżeniami. Redux wyświetla panel ustawień przez klasyczny interfejs administracyjny (Settings API), a nie przez edytor witryny. W podejściu hybrydowym, motyw blokowy plus panel Redux dla ustawień globalnych (kolory, typografia, skrypty analityczne), to połączenie działa. W wersji 4.5.11 bezpośrednia integracja z theme.json nie jest zaimplementowana: wartości trzeba pobierać w szablonach przez mytheme_get_option() i osadzać jako zmienne CSS. Dla środowiska czysto FSE, gdzie wszystkie ustawienia mają znajdować się w edytorze witryny, Redux jest zbędny; dla motywów klasycznych i hybrydowych to jedna z najlepszych opcji.

Co zrobić, gdy Redux koliduje z inną wtyczką korzystającą z tej samej biblioteki?

To znany problem „podwójnego dołączania". Sprawdzenie if ( ! class_exists( 'Redux' ) ) przed require_once gwarantuje, że framework załaduje się dokładnie raz: WordPress wykonuje PHP sekwencyjnie, a pierwsze require_once czyni kolejne wywołania nieszkodliwymi. Jeśli Państwa motyw i zewnętrzna wtyczka oba ciągną Redux, załaduje się ta kopia, która zainicjalizowała się jako pierwsza, a panele obu produktów będą nadal działać. Przy znacznej różnicy wersji głównych może wystąpić niekompatybilność na poziomie API, którą leczy się aktualizacją opóźnionej strony do bieżącego wydania.

Czy do używania Redux Framework w komercyjnym motywie potrzebna jest licencja?

Nie. Redux jest rozpowszechniany na licencji GPLv2, tej samej co WordPress. Można swobodnie dołączać framework do komercyjnych motywów i wtyczek, sprzedawać je na ThemeForest, dystrybuować przez własną stronę. Jedyne ograniczenie GPLv2: dzieła pochodne również muszą być na GPLv2, ale wymóg ten dotyczy kodu źródłowego, a nie treści witryny użytkownika końcowego. Redux Pro (dodatkowe pola, rozszerzony customizer, priorytetowe wsparcie) to osobny płatny produkt, nieobowiązkowy do działania frameworka.

Co robić, jeśli po aktualizacji WordPressa panel Redux przestał się otwierać?

Scenariusz: po dużej aktualizacji WP biały ekran na stronie ustawień motywu. Kolejność działań: po pierwsze, proszę sprawdzić, czy mają Państwo zainstalowaną wersję Redux nie niższą niż 4.5.11 (kompatybilność z WP 7.0). Po drugie, proszę na chwilę włączyć 'dev_mode' => true i sprawdzić wyjście błędów PHP na ekranie ustawień, Redux w trybie deweloperskim pokazuje szczegółowy log. Po trzecie, jeśli błąd dotyczy konkretnego pola, proszę sprawdzić, czy nie używają Państwo przestarzałego typu (search został usunięty w Redux 3.x, divide został przemianowany). Aktualna lista pól znajduje się zawsze w dokumentacji Redux.

Czy warto używać Redux Framework w 2026 roku

Redux Framework to dojrzały, aktywnie utrzymywany produkt, który ma na koncie 32 miliony pobrań i społeczność liczącą ponad 270 kontrybutorów na GitHubie. Jeśli budują Państwo klasyczny lub hybrydowy motyw WordPress i potrzebują panelu ustawień z bogatym zestawem pól, podglądem na żywo w customizerze i dynamicznym CSS, Redux zaoszczędzi Państwu tygodni prac programistycznych i da wynik zgodny ze standardami bezpieczeństwa WordPress (PHPCS, eskejpowanie, walidacja).

Architektonicznie najlepszym sposobem integracji jest wyniesienie frameworka do zależnej wtyczki motywu przez require_once ze sprawdzeniem class_exists. Daje to i czystą bazę kodu, i ochronę przed konfliktami podwójnego dołączania, i przejrzystą ścieżkę aktualizacji.

Kiedy Redux nie jest potrzebny: robią Państwo lekki motyw bez panelu ustawień; pracują Państwo w środowisku czysto FSE (motyw blokowy z theme.json); mają już Państwo wdrożone ACF z Options Pages dla metapól. W tych przypadkach ciągnięcie Redux dla jednego przycisku włącz/wyłącz to jak strzelanie z armaty do wróbli: framework doda ~2 MB do rozmiaru motywu bez proporcjonalnej korzyści.

Przed rozpoczęciem pracy proszę zajrzeć do oficjalnej dokumentacji na stronie twórców Redux i do repozytorium na GitHubie, tam też można zgłosić błąd lub zaproponować nową funkcję. Jeśli potrzebują Państwo pomocy z konkretnym typem pola lub argumentem, proszę pisać w komentarzach, wspólnie to rozwiążemy.