Button

Use a Button for anything that happens in the page — submitting a form, opening a dialog, starting a request. Its appearance is set by two independent props: variant is how loud the button is, tone is which colour set it draws from. Everything else the component adds on top of Base UI is about states you would otherwise have to wire yourself: a loading state that blocks double submits without losing focus, and square icon-only sizing that holds a 24px hit target.

Import

import { Button } from "@forte-ui/react";

Examples

Tones

variant and tone combine freely, and all sixteen pairs are defined. That means emphasis and meaning stay separate decisions: tone="danger" variant="solid" is the destructive action you want people to find, while tone="danger" variant="outline" is the same meaning at low emphasis — the right shape for a delete sitting among other row actions.

Sizes

size sets the height, horizontal padding and font size. The values come from the control tokens, so the ambient data-forte-density setting moves them too: size="sm" is 28px tall by default and exactly 24px under data-forte-density="compact", which is the SC 2.5.8 floor — the density scale deliberately stops there. fullWidth is separate from size — it stretches the button to its container, for stacked forms and mobile action bars.

Loading

loading shows a spinner, hides the label from paint while keeping its width so the button cannot resize under the pointer, sets aria-busy, and blocks activation. Use it for the span of one request, and pair it with a loadingLabel that names the operation.

The indicator is Spinner's ring, rendered decorative and at tone="current" — it takes the button's own text colour, so it stays legible through every variant and tone, and it leaves the announcement to aria-busy and loadingLabel rather than opening a second live region for the same wait. Size it with --forte-button-spinner-size.

Icon-only

iconOnly makes the button square, guarantees the icon --forte-button-icon-padding of space on every side, and floors the square at the control height and at --forte-target-min (24px) so a small icon button still meets WCAG SC 2.5.8. When icon plus padding outgrows that floor the button grows with it, so the icon never crowds the corners — which matters most under data-forte-radius="pill", where the corner is the nearest point of the curve. It is a shape, not a fifth variant: every variant, tone and size works exactly as it does with a label. The icon itself should be aria-hidden — the button's name comes from aria-label.

You do not have to size the glyph. Button sizes a direct svg child of its content from --forte-button-icon-size, which tracks size one step above the label on the same scale — 14px, 16px, 18px. That is there because an icon set's own default is whatever that set picked, and here it decides geometry rather than just weight: lucide draws at 24px, which turns a 36px md button into a 42px one that no longer lines up with the controls beside it. Set the knob, or put a size class on the icon, when you want something else — only a direct child is touched, so a composed forte-ui component keeps sizing its own glyphs.

Rendering as another element

render replaces the rendered tag, and nativeButton={false} tells Base UI the replacement is not a <button> so it supplies button semantics itself — role="button" plus Enter and Space activation. For an anchor that genuinely navigates, pass role="link" back so the element keeps the semantics its behaviour actually matches.

Accessibility

The focus ring is an outline, not a box-shadow, so it follows the button's border radius and survives forced-colors mode, where box shadows are stripped.

Two disabled states behave differently, and the difference matters. A plain disabled button is removed from the tab order: a keyboard or screen reader user tabbing through the page never lands on it, so any explanation of why it is unavailable has to live somewhere they will actually reach. A loading button keeps focusableWhenDisabled on for the duration, which is what stops the browser from blurring it — focus stays put, and aria-busy and loadingLabel stay on the element the user is still on. You can pass focusableWhenDisabled explicitly to get the same reachability for an ordinary disabled button.

Theming

Every property below is declared on the button's own root element. That means setting one on :root, on a theme class or on a wrapper has no effect — the element's own declaration wins over an inherited value. Override them on the button itself, through the className prop (an unlayered rule beats the library's @layer forte.components, whatever its specificity) or an inline style. To move every button at once, re-point the global tokens in the Default column instead — --forte-color-*, --forte-radius-*, --forte-control-* and --forte-font-* are only read here, never re-declared, so those do inherit from :root or a theme scope. State is exposed on data attributes — data-variant, data-tone, data-size, data-loading, data-icon-only, data-full-width, data-disabled — which is also what Tailwind arbitrary variants like data-[variant=solid]:… target.

The two groups are layered: variant decides which of the --forte-button-tone-* values become the background, text and border slots, and tone decides what those values are. To restyle a whole tone, override the tone properties; to restyle one button, override the slots directly.

.checkout-cta {
  --forte-button-radius: var(--forte-radius-full);
  --forte-button-tone-solid: var(--forte-color-secondary);
  --forte-button-tone-on-solid: var(--forte-color-on-secondary);
}

API reference

The table above is generated from the component's TypeScript source. Button also forwards everything Base UI's Button accepts — render, nativeButton, disabled — along with the usual <button> attributes such as type, form, onClick and any aria-* prop.