Breaking changes

Chakra UI с каждым крупным релизом внедряет изменения, которые могут нарушить обратную совместимость с предыдущими версиями. Эти изменения затрагивают как структуру компонентов, так и их API, стилизацию и поведение. Важно понимать основные моменты, чтобы обновление библиотек происходило без ошибок.

1. Изменения в системе темы

Цветовые палитры и переменные: Ранее Chakra UI использовал строгую иерархию ключей для цветов (brand.500, gray.100). В новых версиях ключи могут быть переопределены или удалены. Компоненты, которые ссылались на старые ключи напрямую через colorScheme или bg, могут перестать корректно отображать стили.

FontSizes и lineHeights: API шрифтов было пересмотрено. Множество значений sm, md, lg теперь имеют новые числовые значения, что может вызвать визуальные расхождения при обновлении.

Пример обновления темы:

import { extendTheme } from '@chakra-ui/react';

const theme = extendTheme({
  colors: {
    brand: {
      500: "#1a202c", // старый ключ может быть удален
    },
  },
});

Необходимо проверять все кастомные ключи и соответствие новым стандартам.

2. Компоненты с изменёнными пропсами

Button:

  • Проп variantColor был заменён на colorScheme. Использование старого пропа приведёт к предупреждению или полной неработоспособности.
<Button colorScheme="teal">Кнопка</Button>

Input и Textarea:

  • Проп isFullWidth заменён на size="full".
  • Проп variant изменил список допустимых значений (outline, filled, flushed, unstyled).

Stack и Flex:

  • spacing теперь принимает только числовые значения или строку с единицами ("8px", "1rem"). Ранее поддерживались дробные числа без единиц, что может вызвать визуальные баги.

3. Изменения в хук-API

useDisclosure:

  • Ранее возвращал объект { isOpen, onOpen, onClose }. В новых версиях возвращается также onToggle по умолчанию, а использование старого объекта без деструктуризации может вызвать ошибки.

useBreakpointValue:

  • Теперь возвращает значение undefined при отсутствии подходящего брейкпоинта вместо значения по умолчанию. Это требует проверки кода на наличие fallback значений.

4. Обновления в системных компонентах

Box и Grid:

  • Система sx была удалена из Box, теперь следует использовать __css или стандартные пропсы компонента.
  • Grid больше не поддерживает автоматическое вычисление gridGap через числовые значения без единиц.

Пример исправления:

<Box __css={{ margin: "16px", padding: "8px" }} />

5. Типизация и TypeScript

  • Типы для Chakra UI компонентов были полностью пересмотрены.
  • colorScheme теперь строго типизирован как ключи палитры темы. Старые значения или произвольные строки вызовут ошибку компиляции.
  • Использование пропсов, которые были deprecated, теперь приводит к TS ошибкам, а не просто предупреждениям.

6. Различия в поведении провайдеров

ChakraProvider:

  • В новых версиях CSSReset интегрирован по умолчанию. Явное включение reset может вызвать конфликты стилей.
  • Проп theme теперь поддерживает только объект, созданный через extendTheme. Прямое передание старой структуры темы вызовет баги.

ColorModeProvider:

  • Поведение initialColorMode изменено: теперь при отсутствии сохранённого значения в localStorage применяется система пользователя, а не дефолтный light.

7. Удалённые и deprecated компоненты

Некоторые компоненты полностью удалены или заменены:

  • ModalCloseButton теперь должен быть дочерним элементом ModalContent для корректной работы.
  • MenuDivider заменён на Divider внутри MenuList.
  • Старые иконки из @chakra-ui/icons могут быть удалены или заменены на версии с новым tree-shaking.

8. Рекомендации при обновлении

  • Проверять все кастомные темы на соответствие новым ключам.
  • Использовать автоматические инструменты миграции, если они предоставлены.
  • Внимательно проверять TypeScript-компиляцию, так как ошибки могут быть скрыты визуально, но критичны для работы приложения.
  • Тестировать ключевые компоненты интерфейса (Button, Input, Stack, Grid) после обновления.

Chakra UI версии 2.x и выше требует внимательного подхода к обновлению, особенно для проектов с кастомными темами и сложными интерфейсами. Основные сломанные места — это пропсы компонентов, система темы и хук-API. Правильное применение новых стандартов минимизирует риски и сохранит консистентность UI.

Оглавление