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 color 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. The default is neutral: a view has many buttons and one call to action, so an ordinary button reads as a control and tone="primary" is kept for the action you want found — which is what keeps the accent legible as a signal.

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 color, 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 and keeps it on the control height. The space around the icon is not a fixed padding: --forte-button-icon-padding is derived from the height and --forte-button-icon-size, so a sm icon button is the 28px the Sizes section promises and sits level with a labeled button, a Toggle or a ThemeToggle beside it, at every size and under every data-forte-density. The square is floored at --forte-target-min (24px) so a small icon button still meets WCAG SC 2.5.8, and it only grows when something bigger than the knob says is dropped in — a consumer-sized icon — keeping the same padding around it, so the icon never crowds the corners 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 would push a 36px md button out past the controls beside it. Re-point the knob when you want a larger glyph — the padding follows it, so the square stays on the control height until the glyph outgrows it — or put a size class on the icon; only a direct child is touched, so a composed forte-ui component keeps sizing its own glyphs.

An Avatar works as the icon too — the usual shape of an account menu's trigger. A direct Avatar.Root child takes --forte-button-avatar-size, two thirds of the control height, and the padding derives from that diameter instead of the glyph's, so the square stays on the control height and sits level with a ThemeToggle beside it rather than growing around the avatar's own size. That prop is overridden inside an icon-only button — re-point the knob to change the diameter, and once it outgrows the height the square grows with it, as it does for any oversized icon.

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 behavior 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-gray-*, --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.