useClipboard

useClipboard — это хук библиотеки Chakra UI, предназначенный для удобной работы с буфером обмена браузера. Он предоставляет простой API для копирования текста в буфер обмена и отслеживания состояния копирования. Хук инкапсулирует взаимодействие с Web API буфера обмена и упрощает реализацию распространённых интерфейсных сценариев: кнопки «Скопировать», временные уведомления об успешном копировании, автоматический сброс состояния.

Функциональность особенно востребована в интерфейсах, где необходимо быстро копировать строки — ссылки, токены доступа, фрагменты кода, команды терминала, идентификаторы, адреса и другие текстовые значения.

Подключение

Хук импортируется из пакета @chakra-ui/react.

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

Базовый синтаксис

const { value, onCopy, hasCopied } = useClipboard(valueToCopy)

Хук принимает строку и возвращает набор свойств и функций для работы с копированием.

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

value

Строка, переданная в хук для копирования.

const { value } = useClipboard("Hello")

В большинстве случаев напрямую не используется, но может применяться при построении компонентов интерфейса.

onCopy

Функция, выполняющая копирование текста в буфер обмена.

const { onCopy } = useClipboard("Hello")

При вызове onCopy() значение копируется в буфер обмена.

hasCopied

Булево значение, отражающее факт успешного копирования.

const { hasCopied } = useClipboard("Hello")

После выполнения onCopy() значение становится true и затем автоматически сбрасывается через заданное время.

Это состояние удобно использовать для:

  • изменения текста кнопки
  • отображения уведомлений
  • переключения иконок
  • временной индикации действия

Простейший пример

Интерфейс с кнопкой копирования текста.

import { Button } from "@chakra-ui/react"
import { useClipboard } from "@chakra-ui/react"

function Example() {
  const { hasCopied, onCopy } = useClipboard("https://example.com")

  return (
    <Button onCl ick={onCopy}>
      {hasCopied ? "Скопировано" : "Скопировать"}
    </Button>
  )
}

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

  1. useClipboard получает строку.
  2. При нажатии кнопки вызывается onCopy.
  3. Текст копируется в буфер обмена.
  4. hasCopied становится true.
  5. интерфейс обновляет надпись.

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

Часто требуется копировать содержимое текстового поля.

import { Input, Button, HStack } from "@chakra-ui/react"
import { useClipboard } from "@chakra-ui/react"
import { useState } from "react"

function InputCopy() {
  const [value, setValue] = useState("API_KEY_123456")
  const { onCopy, hasCopied } = useClipboard(value)

  return (
    <HStack>
      <Input value={value} onCha nge={(e) => setValue(e.target.value)} />
      <Button onCl ick={onCopy}>
        {hasCopied ? "Скопировано" : "Копировать"}
      </Button>
    </HStack>
  )
}

Особенности реализации:

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

Параметры хука

useClipboard принимает второй аргумент — объект конфигурации.

useClipboard(value, options)

timeout

Определяет время (в миллисекундах), через которое состояние hasCopied будет сброшено.

По умолчанию используется 1500 мс.

const { hasCopied, onCopy } = useClipboard(text, {
  timeout: 3000
})

В этом случае сообщение о копировании будет отображаться 3 секунды.

Пример с кастомным временем

function CopyExample() {
  const { hasCopied, onCopy } = useClipboard("secret_token", {
    timeout: 5000
  })

  return (
    <Button onCl ick={onCopy}>
      {hasCopied ? "Токен скопирован" : "Скопировать токен"}
    </Button>
  )
}

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

Интерфейсы часто используют визуальную индикацию вместо текста.

import { IconButton } from "@chakra-ui/react"
import { CheckIcon, CopyIcon } from "@chakra-ui/icons"

function CopyIconButton() {
  const { hasCopied, onCopy } = useClipboard("npm install chakra-ui")

  return (
    <IconButton
      onCl ick={onCopy}
      icon={hasCopied ? <CheckIcon /> : <CopyIcon />}
    />
  )
}

После копирования иконка меняется.

Копирование динамического контента

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

function CopyUserId({ userId }) {
  const { onCopy, hasCopied } = useClipboard(userId)

  return (
    <Button onCl ick={onCopy}>
      {hasCopied ? "ID скопирован" : "Скопировать ID"}
    </Button>
  )
}

Если userId меняется, хук автоматически работает с новым значением.

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

Пример интерфейса с копированием нескольких элементов.

function CopyList({ items }) {
  return (
    <>
      {items.map((item) => {
        const { onCopy, hasCopied } = useClipboard(item)

        return (
          <Button key={item} onCl ick={onCopy}>
            {hasCopied ? "Скопировано" : item}
          </Button>
        )
      })}
    </>
  )
}

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

Работа внутри сложных компонентов

useClipboard часто используется в комбинации с компонентами:

  • InputGroup
  • Tooltip
  • Code
  • Badge
  • Menu

Пример копирования команды терминала.

import { Box, Button, Code, HStack } from "@chakra-ui/react"

function CommandCopy() {
  const command = "npm install @chakra-ui/react"
  const { onCopy, hasCopied } = useClipboard(command)

  return (
    <HStack>
      <Code>{command}</Code>
      <Button size="sm" onCl ick={onCopy}>
        {hasCopied ? "OK" : "Copy"}
      </Button>
    </HStack>
  )
}

Комбинирование с Tooltip

Подсказки позволяют показать статус копирования.

import { Tooltip, IconButton } from "@chakra-ui/react"
import { CopyIcon } from "@chakra-ui/icons"

function TooltipCopy() {
  const { onCopy, hasCopied } = useClipboard("example text")

  return (
    <Tooltip label={hasCopied ? "Скопировано" : "Скопировать"}>
      <IconButton icon={<CopyIcon />} onCl ick={onCopy} />
    </Tooltip>
  )
}

Принцип работы

useClipboard реализует несколько внутренних механизмов:

1. Использование Clipboard API

В современных браузерах применяется:

navigator.clipboard.writeText()

2. Фолбэк для старых браузеров

Если API недоступно, создаётся временный элемент textarea, выделяется текст и выполняется команда:

document.execCommand("copy")

3. Управление состоянием

После успешного копирования:

  • hasCopied устанавливается в true
  • запускается таймер
  • состояние автоматически сбрасывается

Типовой пользовательский сценарий

Алгоритм работы компонента:

  1. Пользователь нажимает кнопку.
  2. Вызывается onCopy.
  3. Текст копируется в буфер обмена.
  4. hasCopied становится true.
  5. интерфейс обновляется.
  6. через timeout состояние возвращается в false.

Преимущества использования useClipboard

Упрощение работы с буфером обмена

Нет необходимости вручную реализовывать:

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

Минимальный API

Хук содержит всего несколько свойств, что делает его удобным для интеграции.

Интеграция с React

Полностью соответствует модели управления состоянием React.

Поддержка разных браузеров

Chakra UI реализует fallback-механизмы.

Распространённые сценарии применения

Копирование ссылок

Copy invite link

Копирование API-ключей

API_KEY_3fa9d82...

Копирование команд CLI

npm install package

Копирование кода

const example = true

Копирование идентификаторов

User ID
Transaction ID
Order ID

Паттерн UI: Copy Button

Распространённый интерфейсный паттерн.

Структура компонента:

[ значение ] [ кнопка копирования ]

Реализация:

<HStack>
  <Input value={value} readOnly />
  <Button onCl ick={onCopy}>
    {hasCopied ? "Copied" : "Copy"}
  </Button>
</HStack>

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

Иногда требуется контролировать текст копирования через состояние.

function DynamicCopy() {
  const [text, setText] = useState("Initial")
  const { onCopy } = useClipboard(text)

  return (
    <>
      <Input onCha nge={(e) => setText(e.target.value)} />
      <Button onCl ick={onCopy}>Copy</Button>
    </>
  )
}

Ограничения

Копируется только текст

useClipboard работает исключительно со строками. Копирование файлов, изображений или сложных структур не поддерживается.

Ограничения браузеров

Clipboard API работает только:

  • в защищённом контексте (https)
  • после пользовательского действия (например, клика)

Ограничения безопасности

Некоторые браузеры могут блокировать доступ к буферу обмена:

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

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

Показывать подтверждение копирования

Пользователь должен получать визуальный отклик.

Copied
✔
Toast notification

Использовать короткий timeout

Слишком длительное отображение состояния может ухудшить UX.

Оптимальное значение:

1–3 секунды

Добавлять иконки

Иконки значительно повышают читаемость интерфейса.

Использовать Tooltip

Позволяет объяснить назначение кнопки без перегрузки интерфейса.

Архитектурная роль в Chakra UI

useClipboard относится к категории utility hooks библиотеки Chakra UI. Эти хуки предназначены для решения конкретных задач интерфейса и используются совместно с компонентами системы дизайна.

Другие хуки аналогичной категории:

  • управление модальными окнами
  • управление состоянием раскрытия
  • работа с фокусом
  • обработка медиазапросов

useClipboard обеспечивает декларативный и компактный способ интеграции функциональности копирования в интерфейсы приложений на базе React.

Оглавление