useToken

Хук useToken предназначен для получения значений из токенов темы Chakra UI. Он позволяет извлекать реальные значения (цвета, размеры, шрифты и другие параметры), определённые в теме, и использовать их внутри логики компонентов.

В отличие от стандартного применения токенов через пропсы компонентов (bg, color, margin и т.д.), useToken используется внутри JavaScript-логики, когда требуется получить конкретное значение темы для вычислений, динамических стилей или интеграции со сторонними библиотеками.

Токены темы в Chakra UI

В Chakra UI большая часть стилизации строится на дизайн-токенах — значениях, централизованно определённых в теме.

Основные категории токенов:

Категория Пример
colors blue.500, gray.200
space 4, 8, 12
sizes sm, md, lg
fonts heading, body
fontSizes lg, 2xl
radii md, xl
shadows lg, outline
zIndices modal, dropdown

Пример определения токенов в теме:

import { extendTheme } from "@chakra-ui/react"

const theme = extendTheme({
  colors: {
    brand: {
      500: "#4C6FFF",
      600: "#3B5BDB"
    }
  }
})

Токен brand.500 становится доступным во всей системе Chakra UI.

Назначение useToken

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

Например:

  • получение hex-цвета
  • вычисление динамических стилей
  • передача значений в canvas, charts, animation libraries
  • использование в CSS-in-JS вычислениях
  • синхронизация дизайна со сторонними UI-библиотеками

Сигнатура хука

const values = useToken(scale, tokens)

Параметры:

Параметр Описание
scale раздел темы (colors, space, sizes и т.д.)
tokens массив имён токенов

Возвращает:

  • массив реальных значений токенов.

Базовый пример

Получение значения цвета из темы:

import { useToken } from "@chakra-ui/react"

function Example() {
  const [blue500] = useToken("colors", ["blue.500"])

  return <div style={{ background: blue500 }}>Box</div>
}

blue500 будет содержать:

#3182ce

То есть фактическое значение цвета из темы Chakra UI.

Получение нескольких токенов

useToken может возвращать сразу несколько значений.

const [blue500, red500, green500] = useToken("colors", [
  "blue.500",
  "red.500",
  "green.500"
])

Полученные значения:

#3182ce
#e53e3e
#38a169

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

<div style={{ background: blue500, borderColor: red500 }} />

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

useToken работает не только с цветами.

Пример получения значений отступов:

const [space4, space8] = useToken("space", ["4", "8"])

Результат:

1rem
2rem

Пример применения:

<div style={{ padding: space4, margin: space8 }}>
  Content
</div>

Работа с кастомными токенами

Если в теме добавлены собственные токены, useToken может извлекать и их.

Пример темы:

const theme = extendTheme({
  colors: {
    brand: {
      500: "#4C6FFF",
      700: "#2A3EB1"
    }
  }
})

Получение значений:

const [brand500, brand700] = useToken("colors", [
  "brand.500",
  "brand.700"
])

Использование с графическими библиотеками

Одно из распространённых применений — передача цветов темы в библиотеки графиков.

Пример с chart-библиотекой:

const [primaryColor] = useToken("colors", ["blue.500"])

const chartOptions = {
  datasets: [
    {
      borderColor: primaryColor
    }
  ]
}

Так обеспечивается полная синхронизация дизайна интерфейса и графиков.

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

const [color] = useToken("colors", ["purple.500"])

ctx.fillStyle = color
ctx.fillRect(0, 0, 100, 100)

Использование в анимациях

В библиотеках анимации часто требуется конкретное значение цвета.

Пример с Framer Motion:

const [color] = useToken("colors", ["pink.400"])

<motion.div
  animate={{ backgroundColor: color }}
/>

Получение значений шрифтов

useToken может извлекать значения шрифтов.

const [headingFont] = useToken("fonts", ["heading"])

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

<div style={{ fontFamily: headingFont }}>
  Title
</div>

Получение значений радиусов

const [radius] = useToken("radii", ["lg"])

Применение:

<div style={{ borderRadius: radius }} />

Работа с sizes

const [size] = useToken("sizes", ["container.lg"])

Пример:

<div style={{ maxWidth: size }}>
  Content
</div>

Использование вместе с useTheme

useTheme возвращает всю тему, а useToken извлекает конкретные значения.

Пример:

import { useTheme, useToken } from "@chakra-ui/react"

function Example() {
  const theme = useTheme()
  const [color] = useToken("colors", ["blue.500"])

  console.log(theme)
  console.log(color)
}

Разница между useToken и useTheme

Хук Назначение
useTheme возвращает весь объект темы
useToken возвращает конкретные значения токенов

useToken удобнее, когда требуется не вся тема, а отдельные значения.

Пример динамических стилей

function Card() {
  const [bg, shadow] = useToken("colors", ["gray.100"])
  const [boxShadow] = useToken("shadows", ["lg"])

  return (
    <div
      style={{
        background: bg,
        boxShadow: boxShadow,
        padding: "20px"
      }}
    >
      Card
    </div>
  )
}

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

useToken позволяет использовать значения темы в формулах.

const [space4] = useToken("space", ["4"])

const calculatedPadding = `calc(${space4} * 2)`

Динамический выбор токенов

Иногда требуется выбирать токен в зависимости от состояния.

function Status({ type }) {
  const token =
    type === "success"
      ? "green.500"
      : "red.500"

  const [color] = useToken("colors", [token])

  return <div style={{ color }}>{type}</div>
}

Использование внутри кастомных хуков

useToken может применяться внутри собственных React-хуков.

function useBrandColors() {
  const [primary, secondary] = useToken("colors", [
    "brand.500",
    "brand.600"
  ])

  return { primary, secondary }
}

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

const { primary } = useBrandColors()

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

useToken является лёгким хуком:

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

Однако рекомендуется:

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

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

1. Canvas и WebGL

canvas.fillStyle = themeColor

2. SVG-графика

stroke={color}

3. графики и диаграммы

chartColor = themeColor

4. анимации

animate={{ backgroundColor: color }}

5. динамические вычисления CSS

calc(themeSpacing * 2)

Частые ошибки

Ошибка: ожидание строки вместо массива

const color = useToken("colors", "blue.500")

Правильно:

const [color] = useToken("colors", ["blue.500"])

Ошибка: неправильный scale

useToken("color", ["blue.500"])

Правильно:

useToken("colors", ["blue.500"])

Ошибка: использование вне ChakraProvider

useToken работает только внутри дерева компонентов Chakra UI.

<ChakraProvider>
  <App />
</ChakraProvider>

Когда использовать useToken

Использование оправдано в следующих случаях:

  • требуется получить реальное значение токена
  • значение используется в JavaScript-логике
  • интеграция со сторонними библиотеками
  • работа с canvas / SVG / charts
  • вычисление динамических CSS-значений

Если значение используется только в JSX-пропсах Chakra UI, предпочтительнее писать:

<Box bg="blue.500" />

Вместо:

const [color] = useToken("colors", ["blue.500"])
<Box bg={color} />

Роль useToken в архитектуре Chakra UI

Хук выполняет важную функцию в экосистеме Chakra UI:

  • соединяет дизайн-систему и JavaScript-логику
  • обеспечивает доступ к дизайн-токенам вне JSX
  • позволяет использовать тему в любых вычислениях

Это делает Chakra UI полноценной design-system платформой, где единые значения темы используются не только для компонентов интерфейса, но и для любых визуальных вычислений внутри приложения.

Оглавление