useBreakpointValue

Адаптивность интерфейсов — ключевая особенность современных веб-приложений. Компоненты должны корректно выглядеть и вести себя на различных устройствах: смартфонах, планшетах, ноутбуках и широкоформатных мониторах. Библиотека Chakra UI предоставляет встроенную систему адаптивных значений, основанную на breakpoint-ах.

Для управления значениями, зависящими от ширины экрана, используется хук useBreakpointValue. Он позволяет динамически выбирать значение на основе текущего breakpoint-а.

Этот механизм применяется для:

  • изменения размеров компонентов
  • выбора различных значений отступов
  • переключения вариантов отображения
  • изменения логики поведения элементов
  • управления layout-структурами

Хук возвращает одно значение, которое соответствует текущему breakpoint-у.

Сигнатура useBreakpointValue

const value = useBreakpointValue(values, options)

Параметры

values

Объект или массив значений, соответствующих breakpoint-ам.

options

Дополнительные параметры конфигурации.

Возвращаемое значение

Значение, соответствующее активному breakpoint-у.

Система breakpoint-ов Chakra UI

По умолчанию Chakra UI использует следующую шкалу breakpoint-ов:

Название Минимальная ширина
base 0px
sm 480px
md 768px
lg 992px
xl 1280px
2xl 1536px

Хук автоматически определяет текущий диапазон и возвращает соответствующее значение.

Базовое использование

Простейший пример — изменение размера текста.

import { Text } from "@chakra-ui/react"
import { useBreakpointValue } from "@chakra-ui/react"

function ResponsiveText() {
  const fontSize = useBreakpointValue({
    base: "16px",
    md: "20px",
    lg: "24px"
  })

  return <Text fontSize={fontSize}>Responsive text</Text>
}

Логика работы:

  • base применяется на мобильных устройствах
  • md используется на планшетах
  • lg активируется на больших экранах

Компонент автоматически адаптируется при изменении ширины окна.

Использование массива значений

Вместо объекта можно использовать массив.

const value = useBreakpointValue(["column", "column", "row"])

Порядок элементов массива соответствует breakpoint-ам:

Индекс Breakpoint
0 base
1 sm
2 md
3 lg
4 xl

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

const direction = useBreakpointValue(["column", "row"])

<Flex direction={direction}>
  ...
</Flex>

На мобильных устройствах элементы будут располагаться вертикально, а на больших экранах — горизонтально.

Управление layout-структурой

useBreakpointValue часто используется для изменения структуры интерфейса.

const columns = useBreakpointValue({
  base: 1,
  md: 2,
  lg: 4
})

Применение в Grid:

<Grid templateColumns={`repeat(${columns}, 1fr)`} gap={6}>
  ...
</Grid>

Результат:

Экран Количество колонок
мобильный 1
планшет 2
десктоп 4

Переключение вариантов компонентов

Компоненты Chakra UI часто имеют несколько вариантов оформления.

Хук позволяет менять вариант в зависимости от устройства.

const variant = useBreakpointValue({
  base: "solid",
  md: "outline"
})

<Button variant={variant}>
  Button
</Button>

Поведение:

  • на мобильных устройствах используется solid
  • на больших экранах — outline

Это удобно для уменьшения визуальной нагрузки на маленьких экранах.

Управление размерами элементов

Размеры компонентов также могут изменяться.

const size = useBreakpointValue({
  base: "sm",
  md: "md",
  lg: "lg"
})

<Button size={size}>Action</Button>

Типичное применение:

  • компактные элементы на мобильных устройствах
  • более крупные элементы на десктопах

Управление отступами

Отступы сильно влияют на восприятие интерфейса.

const padding = useBreakpointValue({
  base: 4,
  md: 6,
  lg: 10
})

Использование:

<Box p={padding}>
  Content
</Box>

Мобильная версия получает меньшие отступы, что экономит пространство.

Адаптивное скрытие элементов

Иногда требуется отображать элементы только на определённых устройствах.

const display = useBreakpointValue({
  base: "none",
  md: "block"
})

Пример:

<Box display={display}>
  Desktop content
</Box>

Элемент:

  • скрыт на мобильных устройствах
  • отображается на планшетах и десктопах

Адаптивная логика поведения

Хук можно использовать не только для стилей, но и для логики.

Пример — переключение типа навигации.

const isMobile = useBreakpointValue({
  base: true,
  md: false
})

Дальнейшая логика:

return isMobile ? <MobileMenu /> : <DesktopMenu />

В зависимости от ширины экрана отображается разный компонент.

Использование с Flex

Пример адаптивного layout-а:

const direction = useBreakpointValue({
  base: "column",
  md: "row"
})

const gap = useBreakpointValue({
  base: 4,
  md: 8
})

<Flex direction={direction} gap={gap}>
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Flex>

На мобильных устройствах:

  • вертикальное расположение
  • небольшой промежуток

На десктопе:

  • горизонтальное расположение
  • увеличенный отступ

Опция fallback

Во время серверного рендеринга (SSR) ширина окна неизвестна. Поэтому хук может возвращать undefined.

Для предотвращения этого используется параметр fallback.

const value = useBreakpointValue(
  { base: "mobile", md: "desktop" },
  { fallback: "md" }
)

В этом случае при SSR используется значение breakpoint-а md.

Использование с кастомными breakpoint-ами

Chakra UI позволяет настраивать breakpoint-ы в теме.

const theme = extendTheme({
  breakpoints: {
    base: "0px",
    tablet: "640px",
    laptop: "1024px",
    desktop: "1280px"
  }
})

После этого useBreakpointValue использует новую систему:

const layout = useBreakpointValue({
  base: "stack",
  tablet: "grid",
  desktop: "flex"
})

Отличие от адаптивных пропсов Chakra

Chakra UI поддерживает два основных механизма адаптивности:

1. Responsive props

<Box fontSize={{ base: "16px", md: "20px" }} />

2. useBreakpointValue

const fontSize = useBreakpointValue({
  base: "16px",
  md: "20px"
})

Основные различия

Подход Назначение
Responsive props изменение CSS-свойств
useBreakpointValue управление логикой

useBreakpointValue полезен, когда значение используется внутри JavaScript-логики.

Производительность

Хук использует matchMedia, поэтому изменения breakpoint-ов отслеживаются через медиа-запросы браузера.

Преимущества:

  • отсутствие лишних перерисовок
  • реакция только на изменение breakpoint-а
  • минимальная нагрузка на React-дерево

Практический пример адаптивной карточки

function Card() {
  const direction = useBreakpointValue({
    base: "column",
    md: "row"
  })

  const imageSize = useBreakpointValue({
    base: "100%",
    md: "200px"
  })

  return (
    <Flex direction={direction} borderWidth="1px">
      <Box w={imageSize} bg="gray.200" />
      <Box p={6}>
        Content
      </Box>
    </Flex>
  )
}

На мобильных устройствах:

  • изображение располагается сверху
  • контент — снизу

На десктопе:

  • изображение слева
  • контент справа

Типичные сценарии применения

Переключение layout-а

column → row
grid → flex
stack → sidebar layout

Адаптация размеров

sm → md → lg

Управление логикой интерфейса

mobile menu
desktop navigation
sidebar visibility

Контроль плотности интерфейса

меньше отступов на мобильных
больше пространства на десктопе

Ограничения

useBreakpointValue не должен использоваться для:

  • вычисления сложной бизнес-логики
  • постоянных вычислений в циклах
  • частых обновлений состояния

Хук предназначен исключительно для адаптации интерфейса.

Лучшие практики

1. Минимальное количество breakpoint-ов

Чрезмерная детализация ухудшает поддержку кода.

Оптимально:

base → md → lg

2. Использование семантических значений

Лучше:

compact
comfortable
spacious

чем

4px
8px
16px

3. Избегание дублирования

Если значение используется только для стилей, предпочтительнее responsive props.

4. Разделение логики и стилей

useBreakpointValue используется для:

  • переключения компонентов
  • изменения поведения
  • вычисления layout-параметров

Краткая схема работы

ширина окна
      ↓
определение breakpoint
      ↓
выбор значения из объекта
      ↓
возврат значения в компонент

Таким образом useBreakpointValue становится центральным инструментом адаптивной логики в Chakra UI, позволяя синхронизировать визуальное оформление и поведение интерфейса с текущими условиями отображения.

Оглавление