Створення кастомної панелі налаштувань для теми WordPress, задача, яка здатна розтягнутися на тижні. WordPress Settings API вимагає написання тонни шаблонного коду: реєстрація, рендеринг полів, валідація, збереження. І коли проєкт горить, писати все це з нуля, невиправдана розкіш.

Redux Framework вирішує цю проблему радикально: замість ручної метушні з Settings API ви описуєте потрібні поля в одному конфігураційному файлі, а фреймворк бере на себе все інше, рендеринг, валідацію, екранування, імпорт/експорт і навіть динамічний CSS. На WordPress.org у плагіна понад 32 мільйони завантажень і більше мільйона активних встановлень, і це не маркетингова накрутка, а прямий наслідок того, що Redux реально економить тижні розробки.

У цьому посібнику, покрокове налаштування Redux Framework з нуля до робочої панелі параметрів теми, включно з live-демонстрацією в кастомайзері та безпечним використанням збережених значень на фронтенді.

💡 Швидкий огляд:

• Встановлення Redux Framework: три способи інтеграції в проєкт WordPress
• Підключення фреймворку та створення конфігураційного файлу
• Налаштування аргументів панелі: положення в меню, кастомайзер, Google Fonts
• Додавання розділів і полів введення через єдиний API Redux
• Вилучення збережених значень у шаблонах теми із захистом від помилок

Що таке Redux Framework і навіщо він потрібен

Redux Framework — це безплатний опційний фреймворк з відкритим вихідним кодом для тем і плагінів WordPress. Побудований поверх стандартного WordPress Settings API, але повністю абстрагує його складність. Замість десятків викликів register_setting, add_settings_field і settings_fields ви пишете декларативний масив на PHP і отримуєте повністю робочу, адаптивну панель налаштувань із 49 типами полів на вибір.

Важливо не плутати з JavaScript-бібліотекою Redux для керування станом — це абсолютно різні продукти з однаковою назвою. WordPress-фреймворк з’явився раніше за JS-бібліотеку.

Ключові можливості, які ви отримуєте «з коробки»:

• 49 типів полів: від звичайного тексту та чекбокса до редактора ACE, повторювача (repeater), Google Maps, сортувальника блоків і слайдера зображень;
• Автоматичний вивід CSS: для полів типографіки, кольору, градієнтів, відступів достатньо вказати CSS-селектор, і Redux сам згенерує таблицю стилів із Google Fonts;
• Інтеграція з кастомайзером: однойменний аргумент customizer => true, і вся панель дублюється в WordPress Customizer з живим прев’ю;
• Імпорт/експорт налаштувань: вбудований інструмент перенесення конфігурації між сайтами;
• Компілятор: хук, що спрацьовує при зміні поля з прапорцем compile => true, можна, наприклад, перезібрати SCSS;
• Валідація та екранування: кожне значення проходить санітизацію, що відповідає типу поля,, текстове поле не прийме масив, числове відсіє рядки.

З 2024 року фреймворк розвивається під крилом Team Updraft (Девід Андерсон, творець UpdraftPlus). Поточна версія, 4.5.11 (березень 2026), повна сумісність із WordPress 7.0 і PHP 8.5. Проєкт живе на redux.io, документація, на сайті документації Redux.

Встановлення Redux Framework

Є три способи додати Redux у проєкт. Вибір залежить від архітектури вашої теми та того, як ви плануєте її поширювати.

Окремим плагіном

Встановіть Redux Framework із каталогу WordPress.org як звичайний плагін. Після активації панель параметрів не з’явиться, плагін лише надає API. Усі налаштування ви описуєте в конфігураційному файлі всередині своєї теми.

Плюси: тема залишається легкою (ядро фреймворку не роздуває архів); фреймворк оновлюється незалежно через стандартний механізм WordPress.

Мінуси: ваша тема вимагає наявності стороннього плагіна, користувачеві потрібно встановити й активувати його окремо; за відсутності плагіна панель налаштувань зникає, і потрібно передбачити graceful fallback у коді теми.

В ядрі теми

Скопіюйте папку ReduxCore всередину вашої теми та підключіть її у functions.php. Фреймворк стає невід’ємною частиною теми, користувачеві не потрібно ставити додатковий плагін.

Плюси: панель налаштувань виглядає як нативна частина теми, користувач нічого додатково не встановлює.

Мінуси: розмір архіву теми зростає приблизно на 2 МБ; кожне оновлення фреймворку вимагає оновлення теми з вашого боку; плагін Theme Check може видавати попередження.

У залежному плагіні теми

Рекомендований підхід для преміальних тем. Створіть окремий плагін-компаньйон для вашої теми (у ньому ж зручно тримати кастомні типи записів, шорткоди, віджети) і вбудуйте Redux у нього. У functions.php теми додайте перевірку наявності цього плагіна через TGMPA або аналогічний механізм.

Плюси: чиста архітектура (функціонал теми відокремлений від представлення); фреймворк не роздуває архів теми; оновлення фреймворку не зачіпають код теми напряму.

Мінуси: потрібно написати й підтримувати окремий плагін; дещо вищий поріг входу для інших розробників, які розбиратимуться в проєкті.

Конфігурація Redux не залежить від способу встановлення, подальші кроки ідентичні для будь-якого варіанту.

Загальна конфігурація: підключаємо фреймворк

Всередині плагіна Redux Framework (або завантаженого з офіційного сайту Redux архіву) знайдіть папку ReduxCore, вона містить усе ядро.

Створіть у своєму плагіні (або темі) папку, наприклад optionpanel, і скопіюйте в неї вміст ReduxCore. Поруч покладіть порожній файл config.php, саме в ньому ми опишемо всі розділи та поля панелі налаштувань.

Тепер підключіть фреймворк. В основний файл плагіна (або functions.php теми) додайте:

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

Перевірка class_exists запобігає фатальній помилці, якщо інша частина сайту вже завантажила Redux (наприклад, через окремий плагін). Якщо фреймворк відсутній, панель налаштувань просто не завантажиться, а сайт продовжить працювати.

Після цього можна переходити до створення розділів і полів.

Створення панелі параметрів

Аргументи фреймворку

Перш за все задайте глобальну змінну для зберігання всіх налаштувань, вона знадобиться для отримання значень у шаблонах теми:

1
$opt_name = 'mytheme_options';

Префікс обов'язковий, він запобігає конфліктам імен з іншими плагінами, що використовують Redux. Гарна практика: brandname_themename.

Тепер зберемо масив аргументів. Ось мінімальна робоча конфігурація:

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 );

Розбір ключових аргументів:

• menu_type: submenu, панель з'явиться всередині пункту «Зовнішній вигляд»; menu, окремий пункт верхнього рівня в адмінці;
• customizer: true вмикає дублювання всіх полів у WordPress Customizer з живим переглядом, користувач бачить зміни до збереження;
• dev_mode: увімкніть на час розробки (розширене налагодження, демо-імпорт), але обов'язково вимкніть перед релізом;
• update_notice: завжди false для тем і плагінів, у які вбудовано Redux, ваші користувачі не повинні отримувати сповіщення про оновлення фреймворку окремо від вашого продукту;
• show_import_export: додає інструмент перенесення всіх налаштувань між сайтами одним кліком.

Повний перелік із понад 40 аргументів дивіться в посібнику з аргументів.

Додавання розділів і полів

Розділ — це логічна група полів (вкладка на екрані налаштувань). Мінімальний розділ:

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
) );

Іконки розділів: Redux 4.x підтримує вбудовані іконки WordPress Dashicons (повний список на developer.wordpress.org). Для кастомних іконок використовуйте CSS-класи вашого набору (наприклад, Font Awesome).

Кожне поле — це асоціативний масив з обов'язковими ключами id, type і title. Приклади часто використовуваних типів:

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
),

Для створення підрозділу додайте аргумент 'subsection' => true, поле з'явиться вкладеною вкладкою всередині батьківського розділу.

Список усіх 49 типів із прикладами конфігурації, у розділі типів полів документації Redux.

Використання параметрів у темі

Redux зберігає всі значення в одній глобальній змінній, тій самій, яку ви вказали в $opt_name. Щоб отримати значення в шаблоні, спочатку оголосіть її глобальною. Але пряме оголошення global поза функцією або екшеном, погана практика. Правильний підхід:

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
}

Функція-обгортка робить дві речі: запобігає PHP Notice «undefined index» при зверненні до неіснуючого ключа та надає fallback-значення. У шаблоні використання виглядає так:

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
}

Якщо панель налаштувань ще не налаштована (наприклад, користувач активував тему, але не встановив залежний плагін), $mytheme_options буде порожнім масивом, і mytheme_get_option() мовчки поверне $default, без купи попереджень у debug.log.

Для динамічного CSS використовуйте вбудовану можливість Redux, вкажіть аргумент output у конфігурації поля:

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

Redux автоматично згенерує та вбудує CSS-правило <style>body{background-color:#fff;}</style>, без жодного рядка ручного коду.

Наочно процес встановлення та налаштування полів показано в цьому відеоуроці: від підключення фреймворку до створення першого розділу з селектами та перемикачами:

⁉️🤔 Часті запитання

Чим Redux Framework відрізняється від Carbon Fields, ACF Options Pages та інших рішень?

Redux пропонує 49 типів полів «з коробки» (проти ~25 у Carbon Fields і ~30 у ACF Pro) і фокусується саме на панелях налаштувань теми, а не на метаполях записів. ACF Options Pages — це надбудова над метапольним рушієм, тоді як Redux із самого початку спроєктований під опційні панелі: вбудований імпорт/експорт, компілятор, живий перегляд у кастомайзері, динамічний CSS із Google Fonts. Carbon Fields ближчий за духом, але потребує Composer і неймспейсів, у низці хостингових середовищ це бар'єр. Висновок: якщо ви вже використовуєте ACF для метаполів, беріть ACF Options Pages, щоб не плодити сутності; якщо будуєте тему з нуля і потрібна потужна опційна панель, Redux дасть більше можливостей безкоштовно.

Чи працює Redux Framework із блоковими темами (Full Site Editing)?

Так, але із застереженнями. Redux виводить панель налаштувань через класичний admin-інтерфейс (Settings API), а не через редактор сайту. Для гібридного підходу, блокова тема плюс панель Redux для глобальних налаштувань (кольори, типографіка, скрипти аналітики), зв'язка працює. На момент версії 4.5.11 пряма інтеграція з theme.json не реалізована: значення потрібно видобувати в шаблонах через mytheme_get_option() та інлайнити як CSS-змінні. Для чистого FSE-середовища, де всі налаштування мають жити в редакторі сайту, Redux надлишковий; для класичних і гібридних тем, один із найкращих варіантів.

Як бути, якщо Redux конфліктує з іншим плагіном, що використовує цю саму бібліотеку?

Це відома проблема «подвійного включення». Перевірка if ( ! class_exists( 'Redux' ) ) перед require_once гарантує, що фреймворк завантажиться рівно один раз: WordPress виконує PHP послідовно, і перший же require_once робить наступні виклики нешкідливими. Якщо ваша тема і сторонній плагін обоє тягнуть Redux, завантажиться та копія, яка ініціалізувалася першою, і панелі обох продуктів продовжать працювати. При значній різниці мажорних версій можлива несумісність на рівні API, лікується оновленням відстаючої сторони до актуального релізу.

Чи потрібна ліцензія для використання Redux Framework у комерційній темі?

Ні. Redux поширюється під GPLv2, тією самою ліцензією, що й WordPress. Ви можете вільно включати фреймворк у комерційні теми та плагіни, продавати їх на ThemeForest, поширювати через власний сайт. Єдине обмеження GPLv2, похідні роботи теж мають бути під GPLv2, але ця вимога стосується вихідного коду, а не контенту сайту кінцевого користувача. Redux Pro (додаткові поля, розширений кастомайзер, пріоритетна підтримка), окремий платний продукт, необов'язковий для роботи фреймворку.

Що робити, якщо після оновлення WordPress панель Redux перестала відкриватися?

Сценарій: після мажорного оновлення WP білий екран на сторінці налаштувань теми. Порядок дій: перше, перевірте, що у вас встановлена версія Redux не нижче 4.5.11 (сумісність із WP 7.0). Друге, на хвилину увімкніть 'dev_mode' => true і подивіться вивід помилок PHP на екрані налаштувань, Redux у dev-режимі показує детальний лог. Третє, якщо помилка сиплеться з конкретного поля, перевірте, чи не використовуєте ви deprecated-тип (search видалено в Redux 3.x, divide перейменовано). Актуальний список полів завжди в документації Redux.

Чи варто використовувати Redux Framework у 2026 році

Redux Framework, зрілий, активно підтримуваний продукт, за плечима якого 32 мільйони завантажень і спільнота з понад 270 контриб'юторів на GitHub. Якщо ви будуєте класичну або гібридну тему WordPress і вам потрібна панель налаштувань із багатим набором полів, живим переглядом у кастомайзері та динамічним CSS, Redux зекономить вам тижні розробки й дасть результат, що відповідає стандартам безпеки WordPress (PHPCS, екранування, валідація).

Архітектурно найкращий спосіб інтеграції, винести фреймворк у залежний плагін теми через require_once із перевіркою class_exists. Це дає і чисту кодову базу, і захист від конфліктів подвійного включення, і прозорий шлях оновлення.

Коли Redux не потрібен: ви робите легку тему без панелі налаштувань; працюєте в чистому FSE-середовищі (блокова тема з theme.json); у вас уже розгорнуто ACF з Options Pages для метаполів. У цих випадках тягнути Redux заради однієї кнопки ввімкнення/вимкнення — це як стріляти з гармати по горобцях: фреймворк додасть ~2 МБ до розміру теми без співмірної користі.

Перед початком роботи зазирніть в офіційну документацію на сайті розробників Redux і репозиторій на GitHub, там же можна повідомити про баг або запропонувати фічу. Якщо потрібна допомога з конкретним типом поля або аргументом, пишіть у коментарях, розберемося разом.