ThemeProvider

ThemeProvider отдаёт токены kovax-react как CSS-переменные, управляет светлой и тёмной темой и позволяет брендировать как всё приложение, так и отдельный поддерев, без форка компонентов.

Быстрый старт

Оберните приложение один раз. Все компоненты, использующие themeToken() (а это все), начнут читать значения из единого источника правды.

Как только провайдер смонтирован, смена colorMode мгновенно перекрашивает всех потомков — перерендер бизнес-логики не нужен.

Реакция на смену темы

useColorMode() возвращает текущий режим и стабильные сеттеры. Удобно для переключателей, сохранённых предпочтений и синхронизации со сторонними виджетами.

colorMode отражает выбор пользователя, а resolvedColorMode всегда равен "light" или "dark" (system → разрешается через prefers-color-scheme).

colorMode: light

resolvedColorMode: light

Локальные темы

Передайте ref в target — провайдер запишет data-kovax-theme только на этот элемент, и вы сможете показать тёмный виджет внутри светлой страницы (или наоборот).

Светлый остров

Заблокирован на светлой палитре независимо от глобального режима.

Тёмный остров

Заблокирован на тёмной палитре — отлично подходит для hero-блоков и медийных поверхностей.

Своя бренд-палитра

Передайте частичные оверрайды через проп palettes — всё неуказанное берётся из встроенных light/dark палитр.

Нажмите кнопку, чтобы заменить primary на фиолетовую градацию внутри этой карточки.

Текст в бренд-цвете

Чтение активной палитры

useTheme() даёт полный контекст темы — полезно для инструментов дизайна, превью палитр и интеграции с внешними библиотеками.

Эти образцы читаются вживую из useTheme().palette и обновляются при смене режима.

primary.500#3b82f6

secondary.50#f8fafc

secondary.900#0f172a

success.500#10b981

warning.500#f59e0b

error.500#ef4444

Токены в своих компонентах

themeToken("…") возвращает строку var(--kx-…, fallback). Работает в CSS-in-JS, в style-пропах и даже в SSR-разметке — fallback гарантирует корректный вид до гидратации.

Эта карточка собирает themeToken для фона, цвета, паддинга, тени и transition. Переключите глобальный режим в шапке — увидите анимацию.

Серверный рендер

ThemeProvider дружит с SSR. Рендерите его на сервере с известным defaultColorMode (или читайте из cookie), чтобы избежать вспышки темы. Для изолированных деревьев используйте storageKey={false}.

На сервере мы рендерим с defaultColorMode="light" (или с тем, что лежит в cookie), чтобы первый кадр совпал с выбором пользователя — без вспышки и сдвига контента.

Пропсы

Проп	Тип	Описание
`colorMode`	`"light" \| "dark" \| "system"`	Управляемый режим. Если задан, провайдер игнорирует внутренний state и localStorage — управление берёт ваш стор.
`defaultColorMode`	`"light" \| "dark" \| "system"`	Стартовый режим в неуправляемом режиме. По умолчанию "system".
`onColorModeChange`	`(mode, resolved) => void`	Срабатывает на каждое реальное изменение режима (включая смену системного). Удобно для аналитики, cookie или серверных предпочтений.
`storageKey`	`string \| false \| null`	Ключ localStorage для сохранения. Передайте false или null, чтобы выключить (например, для локальных провайдеров).
`palettes`	`{ light?: Partial<ThemePalette>; dark?: Partial<ThemePalette> }`	Частичные оверрайды по сторонам. Сливаются поверх встроенных light/dark палитр (color ramps, base colors, shadows).
`target`	`"documentElement" \| RefObject<HTMLElement>`	Элемент, на который пишется data-kovax-theme. По умолчанию documentElement; передайте ref, чтобы скоупить тему на поддерев.
`nonce`	`string`	nonce, который пробросится в инжектируемый <style>. Нужен для строгого Content-Security-Policy.