Обзор
ИспользуйтеButton для действия и передавайте его видимую метку в качестве дочернего элемента. Используйте IconButton для элементов управления только со значком, задав доступное имя через aria-label или aria-labelledby.
Для повторяющихся вариантов дизайна по умолчанию используйте MainButton
или LightButton из twenty-ui/components.
Оба используют нативные свойства, refs, состояние и поведение рендеринга Button.
Использование
Внешний вид
Сравните варианты, семантические цвета, размеры и типичные состояния по отдельности. В каждой группе изменяется один параметр, а остальные остаются неизменными.solid, outline, soft, ghost или link независимо от цвета neutral, accent, danger или success. Доступны размеры sm и md; по умолчанию используются outline, neutral и md. fullWidth заполняет доступную ширину. startIcon и endIcon принимают элементы и являются декоративными. elevated добавляет тень и размытие фона. Нейтральные кнопки с контуром также получают поверхность с границей и соответствующими цветами текста и взаимодействия. Другие варианты и семантические цвета сохраняют существующую палитру. По умолчанию используется false и не изменяет размер или положение. shortcut отображает подсказки по клавишам на больших экранах; настройте сочетания клавиш в вашем приложении.
Используйте color="inherit" для элементов управления на цветной поверхности. Метка, значки, индикатор загрузки и контурная граница используют цвет окружающего текста. Для заливок при взаимодействии используется полупрозрачный черный цвет. Кнопки с контуром располагаются на прозрачной поверхности с границей currentColor непрозрачностью 25% и используют черные заливки непрозрачностью 10% и 20% при наведении и нажатии. Ghost использует прозрачную, 10%- и 20%-ные черные заливки; soft использует 10%-, 20%- и 30%-ные. Link остается без заливки.
inherit поддерживает outline, ghost, soft и link. Разрешенная комбинация solid и inherit вызывает ошибку времени выполнения, включая значения по умолчанию, заданные ButtonGroup или оберткой. MainButton по умолчанию использует solid, поэтому при наследовании цвета укажите вариант, отличный от solid.
link использует компактный текст без рамки или залитого фона. При любом размере он соответствует высоте своего содержимого, с меньшим шрифтом и более узкими отступами. Его нейтральный цвет использует более выразительный текст при наведении. Внешний вид не определяет семантику: используйте onClick для действий и href для навигации.
disabled и loading предотвращают активацию. Загрузка сохраняет доступность метки и сообщает о состоянии занятости. По умолчанию loadingPosition="center" скрывает содержимое, сохраняя отведенное для него место в макете, и размещает индикатор загрузки по центру. Установите для loadingPosition значение start или end, чтобы дочерние элементы и противоположный значок оставались видимыми, заменяя соответствующий значок индикатором загрузки.
Ваше приложение отвечает за форматирование прогресса и переведенную метку. Передайте полную фразу состояния в качестве дочерних элементов, например Installing (42%).
Управление состоянием
Button запускает действие и не управляет выбранным значением, поэтому у него нет контролируемого или неконтролируемого режима выбора. Его нативное свойство value передает данные формы, а не состояние выбора.
Ваше приложение управляет loading и disabled, для которых по умолчанию установлено значение false. Нажатие кнопки не изменяет эти свойства и не показывает автоматически состояние загрузки во время работы асинхронного обработчика. Явно передавайте текущее состояние приложения.
MainButton и LightButton используют одинаковую модель состояния.
Триггеры всплывающих окон
Создайте триггер всплывающего окна с помощьюButton, LightButton или другой обёртки Button через render. Триггер предоставляет data-popup-open, поэтому кнопка сохраняет фон при наведении, пока всплывающее окно открыто, и использует активный фон при наведении или нажатии. Каждый вариант и цвет сохраняет собственную палитру. Фон ссылок остаётся прозрачным, а отключённые кнопки или кнопки в состоянии загрузки сохраняют отключённый вид. Кнопки с aria-pressed="true" сохраняют существующее оформление переключателя. Состояние всплывающего окна не устанавливает aria-pressed и не представляет выбранное значение.
Будущие возможности
Ваше приложение управляет доступностью функции и её меткой. Создайте отключенную кнопку сBadge в качестве дочернего элемента, чтобы метка оставалась частью доступного имени кнопки. Предоставьте локализованный текст из вашего приложения.
MainButton и LightButton. Она заменяет удалённые свойства soon и soonLabel.
Анимированные значки
ИспользуйтеButton с AnimatedIconCrossfade, чтобы изменять его значок при изменении состояния приложения. Передайте анимированный элемент в startIcon, а метку — в качестве дочернего элемента.
IconButton или LightIconButton и анимируйте содержимое его значка. Когда заголовок раскрывающегося блока управляет раскрытием, сохраняйте его шеврон декоративным и указывайте aria-expanded в элементе управления заголовка. Храните стили анимации вместе с функцией и учитывайте prefers-reduced-motion.
Ссылки и формы
render href отображает якорь с семантикой ссылки, если только вы явно не установите nativeButton в true. Нативные атрибуты якоря, такие как download, hrefLang, ping и referrerPolicy, передаются якорю. Свойства, общие с нативными кнопками, сохраняют свои типы Base UI. Чтобы указать MIME-тип якоря, задайте его в средстве рендеринга, например render={<a href="/records.csv" type="text/csv">Download records</a>} с nativeButton={false} и role="link". Отключенные и загружающиеся ссылки нельзя активировать.
Используйте render для компоновки другого элемента или ссылки маршрутизатора. nativeButton описывает отображаемый элемент и по умолчанию имеет значение true для пользовательских средств рендеринга. Установите nativeButton={false} и role="link" для якоря навигации. Якорь или компонент маршрутизатора может иметь собственный адрес назначения без href у Button.
\<button> оставьте nativeButton равным true. Для ненативного элемента действия, такого как \<div>, используйте nativeButton={false}; Base UI обеспечивает поведение кнопки с клавиатуры. Явно заданные nativeButton или role сохраняются, даже если также указан href.
Для кнопок по умолчанию используется type="button". Для форм явно задавайте type="submit" или type="reset". Нативные атрибуты, обработчики событий, сведения о событиях и ссылки передаются отображаемому корневому элементу. Ссылка получает фактическую кнопку, якорь или пользовательский корневой элемент. Обработчики клавиатуры сохраняют методы событий Base UI, включая preventBaseUIHandler() для отмены встроенного действия клавиатуры. Колбэк рендеринга Base UI получает как свойства корневого элемента, так и текущее отключенное состояние; распределите свойства по корневому элементу, чтобы сохранить поведение композиции.
Значения по умолчанию группы
ButtonGroup предоставляет общие вариант, цвет и размер. Явно заданное свойство у дочернего элемента имеет приоритет над значением по умолчанию группы. Если ни один из них не задает свойство, применяется значение компонента по умолчанию.Миграция с ClickToActionLink
ИмпортируйтеButton из twenty-ui/primitives/input и замените ClickToActionLink на Button variant="link". Сохраните href, target и rel для навигации. Действия без href теперь отображают нативную кнопку с активацией с клавиатуры. Нативные атрибуты, события и ссылки передаются корневому элементу.
Свойства
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
по умолчанию:"false"
Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors.
ReactNode
Decorative content displayed after the label.
boolean
по умолчанию:"false"
Whether the button should be focusable when disabled.
boolean
по умолчанию:"false"
Expands the button to fill its container width.
string
Destination URL. Renders a native anchor when
render is omitted unless nativeButton is explicitly true. Custom renderers retain their own element contract.boolean
по умолчанию:"false"
Shows a loading indicator and disables activation.
"center" | "end" | "start"
по умолчанию:"center"
Where the loading indicator appears.
center hides the content while preserving its layout space; start and end keep children and the opposite icon visible and replace the corresponding icon with the spinner.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.ShortcutDefinition
Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens.
string
Localized text between sequence steps. Defaults to then.
"md" | "sm"
по умолчанию:"md"
Button height:
sm (24px) or md (32px). The link variant uses its content height at either size.ReactNode
Decorative content displayed before the label.
CSSProperties | ((state: ButtonState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
"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.shortcut={['Mod', 'Enter']} для одновременного нажатия клавиш или shortcut={[['G'], ['P']]} для последовательных нажатий. См. Shortcut для вложенных комбинаций и общего форматтера строк.