Перейти к основному содержанию

Обзор

IconButton сочетает Button с квадратной или круглой поверхностью. Передавайте значок как children и задавайте доступное имя с помощью aria-label или aria-labelledby. Содержимое иконки является декоративным и скрыто от вспомогательных технологий.

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

Размеры: xs (20px), sm (24px) и md (32px). Значения по умолчанию: md, outline и neutral. Варианты и цвета соответствуют Button. Используйте shape="round" для круглой кнопки; по умолчанию используется форма square.

Визуальные параметры

Сравнивайте по одному визуальному варианту за раз. Используйте для композиции примеры с именованной всплывающей подсказкой, приподнятые и сгруппированные.

Доступные имена

Используйте aria-label для имени, заданного непосредственно у элемента управления. Если видимый текст уже задает имя действия, используйте aria-labelledby, чтобы ссылаться на него. Требуется как минимум один проп для задания имени.

Подсказка

Добавьте tooltip, чтобы показывать текст при наведении и фокусе с клавиатуры. Сохраняйте aria-label или aria-labelledby в качестве доступного имени действия. Отключенные кнопки и кнопки в состоянии загрузки сохраняют подсказки при наведении.
По умолчанию подсказка отображается снизу, с задержкой 1000ms и смещением 5px. Используйте tooltipPlace, tooltipDelay и tooltipOffset, чтобы настроить её. Без tooltip кнопка рендерится напрямую.

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

Ваше приложение задаёт loading и disabled. Оба предотвращают активацию. При загрузке сохраняются квадратные размеры и доступная метка. Кнопка не отслеживает выбранное значение и не устанавливает состояние загрузки автоматически после нажатия. Нативный фокус с клавиатуры определяется браузером; используйте aria-pressed, когда ваше приложение управляет состоянием переключателя.

Приподнятые действия

Используйте elevated, чтобы добавить тень и размытие фона. Нейтральная контурная кнопка по умолчанию также получает поверхность с рамкой и соответствующими цветами значка и взаимодействия. Другие варианты и семантические цвета сохраняют текущую палитру. Значение elevated по умолчанию — false. Это не изменяет позиционирование, видимость или размер. По умолчанию размер остаётся md (32px); для элемента управления размером 24px задайте size="sm".
Не указывайте elevated или задайте для него значение false, чтобы восстановить стандартный вид. Приподнятые кнопки поддерживают те же всплывающие подсказки, состояния загрузки, ссылки и взаимодействия с клавиатурой. Замените существующие элементы управления FloatingIconButton на IconButton elevated. Передавайте иконку как children, используйте нативный aria-label и сопоставьте small с sm, а medium с md. Укажите size="sm", если предыдущий элемент управления использовал размер по умолчанию. Нативные фокус и aria-pressed заменяют синтетические флаги фокуса и активности. FloatingIconButtonGroup удалён. Используйте ButtonGroup вместе с IconButton для сгруппированных действий и сохраните общую плавающую поверхность в своём макете.

Сгруппированные действия

ButtonGroup задает значения по умолчанию для размера, варианта и цвета, а также для примыкающих углов. Явно заданные пропы дочернего элемента имеют приоритет независимо друг от друга, включая size="xs". Для отдельных кнопок не требуется свойство позиции. Сохраняйте одинаковый размер объединенных кнопок, чтобы их края выравнивались. Задайте размер для группы, и каждая кнопка унаследует его.

Ссылки и формы

Без пользовательского render href рендерит ссылку, если только nativeButton явно не имеет значение true. Для пользовательской навигационной ссылки или ссылки маршрутизатора задайте nativeButton={false} и role="link". Рендерер может сам задавать место назначения без href у IconButton. Сохраняйте nativeButton равным true для пользовательской нативной кнопки и используйте false для ненативного элемента действия. Явно заданные пропы nativeButton и role сохраняются. Отключенные и загружающиеся ссылки нельзя активировать. Маршрутизация остаётся в приложении. Атрибуты нативной кнопки и ссылки, обработчики событий, сведения о событиях, refs и композиция рендеринга передаются в Button. Ссылка ref получает фактический корневой элемент. Композиция Tooltip сохраняет этот корневой элемент и его доступное имя. По умолчанию используется type="button"; для отправки формы явно задайте type="submit".

Компактные и круглые элементы управления

Используйте size="xs" для элемента управления размером 20px и shape="round" для круглых углов. Существующие элементы управления RoundedIconButton становятся IconButton с shape="round", variant="solid" и color="accent". Сопоставьте их прежний размер small с xs, а размер medium — с sm. Укажите дочерние элементы-значки и доступное имя.

Свойства

string
Accessible name describing the action. Required unless aria-labelledby supplies the name.
string
ID of the element supplying the accessible name. Can be used instead of aria-label.
ReactNode
обязательно
Icon content. Decorative and hidden from assistive technology.
string | ((state: ButtonState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "danger" | "inherit" | "neutral" | "success"
по умолчанию:"neutral"
Semantic color of the button. inherit uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults.
boolean
Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors.
boolean
по умолчанию:"false"
Whether the button should be focusable when disabled.
string
Destination URL. Renders a native anchor when render is omitted unless nativeButton is explicitly true. Custom renderers retain their own element contract.
boolean
Shows a loading indicator and disables activation.
boolean
по умолчанию:"true (false for the built-in href anchor)"
Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in href anchor defaults to false; an explicit value takes precedence.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>
Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use nativeButton={false} and role="link" for a custom navigation anchor. Router integration belongs to the caller.
AriaRole
Role of the root element. Use link for custom navigation renderers.
"round" | "square"
по умолчанию:"square"
Square or round icon control.
"md" | "sm" | "xs"
по умолчанию:"md"
Button size: xs (20px), sm (24px), or md (32px).
CSSProperties | ((state: ButtonState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
string
Text displayed when hovering or focusing the button.
number
по умолчанию:"1000"
Delay before showing the tooltip.
number
по умолчанию:"5"
Distance in pixels between the button and the tooltip.
"bottom" | "inline-end" | "inline-start" | "left" | "right" | "top"
по умолчанию:"bottom"
Preferred placement of the tooltip relative to the button.
"ghost" | "link" | "outline" | "soft" | "solid"
по умолчанию:"outline"
Visual treatment of the button surface. link uses compact text styling without a filled surface or border; render composition determines native semantics.