# IconButton ## Кратко `IconButton` — вариант действия только с иконкой, построенный на той же основе, что и `Button`. Это компактный слой действий для случаев, когда видимый текст добавил бы шум, а не ясность. ## Импорты ```tsx import { IconButton, type IconButtonProps, type IconButtonSize, } from '@vega-ui/react'; ``` ## Экспортируемые типы - `IconButtonProps` - `IconButtonSize` ## Базовое использование ```tsx import { Icon, IconButton, Text } from '@vega-ui/react'; import { EllipsisIcon, PencilIcon, Share2Icon } from '@vega-ui/icons'; import { useState } from 'react'; export default function BasicUsage() { const [lastAction, setLastAction] = useState(''); return (
Brand guidelines setLastAction('Rename')}> setLastAction('Share')}> setLastAction('More')}>
{lastAction === '' ? 'Updated 2 hours ago' : `Clicked: ${lastAction}`}
); } ``` ## Варианты - Размеры: `xs`, `sm`, `md`, `lg`, `xl` - Варианты и оформления, унаследованные от основы кнопки - Композиция: кнопка по умолчанию или `asChild` ## Пограничные случаи - Всегда задавайте `aria-label`, потому что видимого текста обычно нет. - Соблюдайте визуальный баланс размера глифа иконки и токена размера кнопки. - Используйте обычный `Button`, когда видимый текст сделал бы действие понятнее. - Если смысл иконки слишком сильно зависит от окружающего контекста, текстовая кнопка обычно надёжнее. ## Частые ошибки - Пропущен `aria-label`. - Длинный текст помещается внутрь `IconButton`. - Действия только с иконкой используются там, где их смысл неузнаваем. ## Примеры ### Базовый #### Базовый: действия в заголовке с явными именами Каждому действию-иконке нужен свой `aria-label`: компонент его не добавляет. Внутри `IconButton` `Icon` без `size` масштабируется вместе с кнопкой через `--icon-size`. ```tsx import { Icon, IconButton, Text } from '@vega-ui/react'; import { EllipsisIcon, PencilIcon, Share2Icon } from '@vega-ui/icons'; import { useState } from 'react'; export default function BasicUsage() { const [lastAction, setLastAction] = useState(''); return (
Brand guidelines setLastAction('Rename')}> setLastAction('Share')}> setLastAction('More')}>
{lastAction === '' ? 'Updated 2 hours ago' : `Clicked: ${lastAction}`}
); } ``` #### Базовый: размеры `size` задаёт сторону квадрата от `xs` до `xl`; вложенная иконка занимает треть размера кнопки. ```tsx import { Icon, IconButton, type IconButtonSize } from '@vega-ui/react'; import { SettingsIcon } from '@vega-ui/icons'; const sizes: IconButtonSize[] = ['xs', 'sm', 'md', 'lg', 'xl']; export default function Sizes() { return (
{sizes.map((size) => ( ))}
); } ``` ### Контролируемый/с состоянием #### Контролируемый/с состоянием: переключатель «Избранное» с aria-pressed Подпись остаётся «Favorite», а состояние хранится в `aria-pressed`, поэтому скринридер объявляет «Favorite, кнопка-переключатель, нажата». Если менять подпись при каждом клике, состояние, наоборот, потеряется. ```tsx import { Icon, IconButton } from '@vega-ui/react'; import { HeartIcon } from '@vega-ui/icons'; import { useState } from 'react'; export default function ParentOwnedFavoriteToggle() { const [favorite, setFavorite] = useState(false); const count = favorite ? 129 : 128; return (
setFavorite(!favorite)} > {count} people saved this recipe
); } ``` #### Контролируемый/с состоянием: копирование с временной обратной связью После копирования иконка на две секунды меняется на галочку, а область статуса объявляет «Copied»: одна только смена иконки для скринридера беззвучна. ```tsx import { Icon, IconButton, VisuallyHidden } from '@vega-ui/react'; import { CheckIcon, CopyIcon } from '@vega-ui/icons'; import { useEffect, useState } from 'react'; const inviteLink = 'https://app.example.com/invite/7Fq2-K9xD'; export default function CopyToClipboard() { const [copied, setCopied] = useState(false); useEffect(() => { if (!copied) return; const timer = setTimeout(() => setCopied(false), 2000); return () => clearTimeout(timer); }, [copied]); const copy = async () => { await navigator.clipboard.writeText(inviteLink); setCopied(true); }; return (
{inviteLink} {copied ? : } {copied ? 'Copied' : ''}
); } ``` ### Форма/интеграция #### Форма/интеграция: очистка и отправка рядом с полем Кнопка очистки использует `type='button'`, чтобы не отправлять форму, и возвращает фокус в поле. Кнопка поиска — настоящий `type='submit'`; запрос читается через `FormData`. ```tsx import type { CSSProperties } from 'react'; import { Icon, IconButton, Label, TextField, TextFieldInput } from '@vega-ui/react'; import { SearchIcon, XIcon } from '@vega-ui/icons'; import { FormEvent, useRef, useState } from 'react'; export default function InlineClearAction() { const input = useRef(null); const [query, setQuery] = useState('quarterly report'); const [submitted, setSubmitted] = useState(''); const clear = () => { setQuery(''); input.current?.focus(); }; const handleSubmit = (event: FormEvent) => { event.preventDefault(); setSubmitted(String(new FormData(event.currentTarget).get('q'))); }; return (
setQuery(event.target.value)} /> {query !== '' && ( )}
{submitted === '' ? 'Press Enter or the search button' : `Searched for “${submitted}”`}
); } ``` ### Раскладка/оверлей #### Раскладка/оверлей: кнопка закрытия в диалоге Стандартная кнопка закрытия оверлея: круглая призрачная кнопка 24×24 внутри `DialogClose asChild`, позиционированная логическими отступами, чтобы зеркалиться в раскладках справа налево. ```tsx import type { CSSProperties } from 'react'; import { Button, Dialog, DialogClose, DialogContent, DialogTrigger, Heading, Icon, IconButton, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; export default function CompactCloseAction() { return (
What’s new in 2.4
Shared libraries, faster exports, and a new dark theme. Press Escape or the cross to return to your work. ); } ``` #### Раскладка/оверлей: тултип для зрячих пользователей `aria-label` даёт кнопке доступное имя для вспомогательных технологий, а `Tooltip` показывает то же имя и сочетание клавиш пользователям мыши и клавиатуры. Тултип связан как описание, поэтому дополнительные детали держите в нём. ```tsx import { Icon, IconButton, Tooltip, TooltipArrow, TooltipContent, TooltipTrigger } from '@vega-ui/react'; import { AlignCenterIcon, AlignLeftIcon, AlignRightIcon } from '@vega-ui/icons'; import { type ReactNode, useState } from 'react'; const alignments: { value: string, label: string, shortcut: string, icon: ReactNode }[] = [ { value: 'left', label: 'Align left', shortcut: 'Ctrl+Shift+L', icon: }, { value: 'center', label: 'Align center', shortcut: 'Ctrl+Shift+E', icon: }, { value: 'right', label: 'Align right', shortcut: 'Ctrl+Shift+R', icon: }, ]; export default function TooltipLabel() { const [alignment, setAlignment] = useState('left'); return (
{alignments.map((item) => ( setAlignment(item.value)} > {item.icon} {item.label} · {item.shortcut} ))}
); } ``` ### Ошибка #### Ошибка: неудачное удаление Удалить заблокированный файл не получается: ошибка выводится под строкой и связана с её кнопкой через `aria-describedby`. Доступное имя включает имя файла, поэтому десять одинаковых иконок корзины всё равно различимы. ```tsx import { HelperText, Icon, IconButton } from '@vega-ui/react'; import { FileTextIcon, Trash2Icon } from '@vega-ui/icons'; import { useState } from 'react'; const initialFiles = [ { name: 'contract-signed.pdf', locked: true }, { name: 'brief-v3.docx', locked: false }, { name: 'moodboard.png', locked: false }, ]; export default function FailedRemoveAction() { const [files, setFiles] = useState(initialFiles); const [error, setError] = useState(''); const remove = (name: string, locked: boolean) => { if (locked) { setError(name); return; } setError(''); setFiles(files.filter((file) => file.name !== name)); }; return (
    {files.map((file, index) => { const failed = error === file.name; const errorId = `remove-error-${file.name}`; return (
  • {file.name} remove(file.name, file.locked)} >
    {failed && ( Signed contracts cannot be removed. Ask an admin to archive it instead. )}
    • ); })}
); } ``` ### Отключённый #### Отключённый: панель инструментов, отключённая через fieldset `
` нативно отключает каждый `IconButton` внутри — удобно для документов только для чтения, где недоступна вся панель сразу. ```tsx import { Button, Fieldset, FieldsetLegend, Icon, IconButton } from '@vega-ui/react'; import { BoldIcon, ItalicIcon, LinkIcon, ListIcon } from '@vega-ui/icons'; import { useState } from 'react'; export default function BlockedIconAction() { const [locked, setLocked] = useState(true); return (
{locked ? 'Formatting (read-only document)' : 'Formatting'}
); } ``` ### Пограничный случай #### Пограничный случай: кнопки масштаба на границах Кнопки отключаются на первом и последнем шаге масштаба, вычисленных из списка шагов. Когда кнопка отключает саму себя в фокусе, браузер теряет фокус, поэтому значение стоит между кнопками, где пользователь его видит. ```tsx import { Icon, IconButton } from '@vega-ui/react'; import { MinusIcon, PlusIcon } from '@vega-ui/icons'; import { useState } from 'react'; const steps = [25, 50, 75, 100, 150, 200, 400]; export default function ZoomControls() { const [index, setIndex] = useState(3); const atMin = index === 0; const atMax = index === steps.length - 1; return (
setIndex(index - 1)} > {steps[index]}% setIndex(index + 1)} >
); } ``` ## Анатомия ### Обзор `IconButton` — одиночная поверхность действия только с иконкой, построенная на `ButtonBase`. Её анатомия — один интерактивный корень и иконка без видимой текстовой подписи. ### Обязательные части #### `IconButton` Обязательная часть. Отвечает за размер и визуальные пропсы базовой кнопки, такие как вариант и оформление. ### Необязательные части `IconButton` не предоставляет публичных дочерних частей, но обычно его комбинируют с `Icon`. ### Порядок композиции 1. `IconButton` 2. содержимое-иконка ### Допустимые варианты композиции ```tsx import { Icon, IconButton, Text } from '@vega-ui/react'; import { EllipsisIcon, PencilIcon, Share2Icon } from '@vega-ui/icons'; import { useState } from 'react'; export default function BasicUsage() { const [lastAction, setLastAction] = useState(''); return (
Brand guidelines setLastAction('Rename')}> setLastAction('Share')}> setLastAction('More')}>
{lastAction === '' ? 'Updated 2 hours ago' : `Clicked: ${lastAction}`}
); } ``` ### Недопустимые варианты композиции #### Кнопка только с иконкой без доступной подписи Действие становится непонятным для вспомогательных технологий, а часто и для зрячих пользователей. #### Длинный текст внутри `IconButton` Если действию нужны видимые слова, используйте `Button`.