Button

Flat and raised buttons, icon buttons, and groups.

Base UI ButtonSource

Appearances and variants

Use raised by default, flat in toolbars and repeated list actions, and outline next to a raised button. Use one primary per section for the main path. Use danger only for the final destructive act.

secondaryprimary · maindanger · finalraised · default
flat · toolbars, lists
outline · secondary

Sizes and states

Use md by default, sm in toolbars, table rows, cards, and status bars, and lg only for marketing hero calls to action. Click Save to see the loading state.

raised
flat
outline

With an icon

icon goes before the label. iconPosition="end" moves it after. iconEnd adds a second icon.

icon
iconPosition="end"
icon + iconEnd

Icon buttons

IconButton shows only an icon, so give it an aria-label.

Sizes
Variants
States

Button groups

Buttons in a ButtonGroup take its appearance, variant, and size, and join edge to edge.

raised · default
flat · toolbars

Usage

These are defaults, not laws. Break one when you have a good reason, or when it makes the design more cohesive or more interesting.

  • Over images, video, or a canvas, use FloatingButton.
  • Confirm actions that cannot be undone with an AlertDialog. Put danger on the confirm button in the dialog, not on the button that opens it.
  • Use loading, not disabled, while a request runs. The width stays the same and the button stays focusable.
  • For navigation, use ButtonLink.
  • To use a library button as a Base UI trigger, pass it to render, for example <Popover.Trigger render={<Button />}>.

API

Props that the library adds. Every part also takes all the Base UI props.

Button

PropTypeDefaultDescription
appearance'flat' | 'raised' | 'outline''raised'The shape: flat, raised 3D, or outlined.
variant'primary' | 'secondary' | 'danger''secondary'The meaning and color: brand orange, neutral, or destructive red.
size'sm' | 'md' | 'lg''md'Height and text size.
iconReactNode–An icon next to the text.
iconEndReactNode–A second icon after the label.
loadingboolean–Shows a spinner and blocks actions. The width does not change.
iconPosition'start' | 'end''start'Which side of the text the icon goes on.

IconButton

PropTypeDefaultDescription
iconReactNode–The icon. Required.
loadingboolean–Replaces the icon with a spinner and blocks actions.
aria-labelstring–The accessible name. Required.

ButtonGroup

PropTypeDefaultDescription
appearance'flat' | 'raised' | 'outline''raised'The shape: flat, raised 3D, or outlined. Sets it for every button in the group.
variant'primary' | 'secondary' | 'danger''secondary'The meaning and color: brand orange, neutral, or destructive red. Sets it for every button in the group.
size'sm' | 'md' | 'lg''md'Sets the size of every button.
disabledbooleanfalseBlocks every button and fades the group as one unit.