Button
Material 3 button specification, hierarchy, usage guidance, expressive sizes and shapes, states, accessibility, and copyable React examples.
Buttons let people initiate actions. Choose the variant from the action's importance and context, then let canonical Material tokens own the visual treatment.
Quick start
Use onPress for the action callback. Omitting size uses the current Material 3 small Button contract.
import { Button } from '@m3-ui/ui';
export function ButtonBasicLiveExample() {
return <Button onPress={() => {}}>Save changes</Button>;
}Material 3 specification
The Material 3 overview and specs pages above are the normative design sources for Button hierarchy and guidance. The tables below are generated from m3-ui's canonical Button token graph, which is reconciled against the audited Material 3 Design Kit, Material Web, and pinned AndroidX Compose sources. Canonical values are generated here rather than copied into prose.
Canonical implementation table
button specification
Generated from packages/tokens/tokens at component.button. Aliases stay visible so semantic roles are not flattened into copied literals.
| Token | Group | Type | Canonical value | Resolved value |
|---|---|---|---|---|
baseline.containerShape | shape | string | full | full |
baseline.iconSize | icon | dimension | 18px | 18px |
baseline.minHeight | size | dimension | 40px | 40px |
baseline.minWidth | size | dimension | 58px | 58px |
baseline.outlineColor | color | string | transparent | transparent |
baseline.outlineWidth | size | dimension | 0px | 0px |
size.extraLarge.containerShapeRound | shape | string | full | full |
size.extraLarge.containerShapeSquare | shape | string | extraLarge | extraLarge |
size.extraLarge.height | size | dimension | 136px | 136px |
size.extraLarge.iconSize | icon | dimension | 40px | 40px |
size.extraLarge.outlineWidth | size | dimension | 3px | 3px |
size.extraLarge.pressedShape | shape | string | large | large |
size.extraLarge.pressedShapeMotion.spring.dampingRatio | shape | number | {motion.spring.standard.fastSpatial.dampingRatio} | 0.9 |
size.extraLarge.pressedShapeMotion.spring.stiffness | shape | number | {motion.spring.standard.fastSpatial.stiffness} | 1400 |
size.extraLarge.selectedContainerShapeRound | shape | string | {component.button.size.extraLarge.containerShapeSquare} | extraLarge |
size.extraLarge.selectedContainerShapeSquare | shape | string | {component.button.size.extraLarge.containerShapeRound} | full |
size.extraSmall.containerShapeRound | shape | string | full | full |
size.extraSmall.containerShapeSquare | shape | string | medium | medium |
size.extraSmall.height | size | dimension | 32px | 32px |
size.extraSmall.iconSize | icon | dimension | 20px | 20px |
size.extraSmall.outlineWidth | size | dimension | 1px | 1px |
size.extraSmall.pressedShape | shape | string | small | small |
size.extraSmall.pressedShapeMotion.spring.dampingRatio | shape | number | {motion.spring.standard.fastSpatial.dampingRatio} | 0.9 |
size.extraSmall.pressedShapeMotion.spring.stiffness | shape | number | {motion.spring.standard.fastSpatial.stiffness} | 1400 |
size.extraSmall.selectedContainerShapeRound | shape | string | {component.button.size.extraSmall.containerShapeSquare} | medium |
size.extraSmall.selectedContainerShapeSquare | shape | string | {component.button.size.extraSmall.containerShapeRound} | full |
size.large.containerShapeRound | shape | string | full | full |
size.large.containerShapeSquare | shape | string | extraLarge | extraLarge |
size.large.height | size | dimension | 96px | 96px |
size.large.iconSize | icon | dimension | 32px | 32px |
size.large.outlineWidth | size | dimension | 2px | 2px |
size.large.pressedShape | shape | string | large | large |
size.large.pressedShapeMotion.spring.dampingRatio | shape | number | {motion.spring.standard.fastSpatial.dampingRatio} | 0.9 |
size.large.pressedShapeMotion.spring.stiffness | shape | number | {motion.spring.standard.fastSpatial.stiffness} | 1400 |
size.large.selectedContainerShapeRound | shape | string | {component.button.size.large.containerShapeSquare} | extraLarge |
size.large.selectedContainerShapeSquare | shape | string | {component.button.size.large.containerShapeRound} | full |
size.medium.containerShapeRound | shape | string | full | full |
size.medium.containerShapeSquare | shape | string | large | large |
size.medium.height | size | dimension | 56px | 56px |
size.medium.iconSize | icon | dimension | 24px | 24px |
size.medium.outlineWidth | size | dimension | 1px | 1px |
size.medium.pressedShape | shape | string | medium | medium |
size.medium.pressedShapeMotion.spring.dampingRatio | shape | number | {motion.spring.standard.fastSpatial.dampingRatio} | 0.9 |
size.medium.pressedShapeMotion.spring.stiffness | shape | number | {motion.spring.standard.fastSpatial.stiffness} | 1400 |
size.medium.selectedContainerShapeRound | shape | string | {component.button.size.medium.containerShapeSquare} | large |
size.medium.selectedContainerShapeSquare | shape | string | {component.button.size.medium.containerShapeRound} | full |
size.small.containerShapeRound | shape | string | full | full |
size.small.containerShapeSquare | shape | string | medium | medium |
size.small.height | size | dimension | 40px | 40px |
size.small.iconSize | icon | dimension | 20px | 20px |
size.small.outlineWidth | size | dimension | 1px | 1px |
size.small.pressedShape | shape | string | small | small |
size.small.pressedShapeMotion.spring.dampingRatio | shape | number | {motion.spring.standard.fastSpatial.dampingRatio} | 0.9 |
size.small.pressedShapeMotion.spring.stiffness | shape | number | {motion.spring.standard.fastSpatial.stiffness} | 1400 |
size.small.selectedContainerShapeRound | shape | string | {component.button.size.small.containerShapeSquare} | medium |
size.small.selectedContainerShapeSquare | shape | string | {component.button.size.small.containerShapeRound} | full |
variant.elevated.containerColor | color | string | {color.role.surfaceContainerLow} | var(--surface-container-low) |
variant.elevated.containerShadowColor | elevation | string | var(--shadow) | var(--shadow) |
variant.elevated.contentColor | color | string | {color.role.primary} | var(--primary) |
variant.elevated.defaultElevation | elevation | string | level1 | level1 |
variant.elevated.disabledElevation | elevation | string | level0 | level0 |
variant.elevated.focusedElevation | elevation | string | level1 | level1 |
variant.elevated.hoveredElevation | elevation | string | level2 | level2 |
variant.elevated.iconColor | color | string | {component.button.variant.elevated.contentColor} | var(--primary) |
variant.elevated.pressedElevation | elevation | string | level1 | level1 |
variant.filled.containerColor | color | string | {color.role.primary} | var(--primary) |
variant.filled.containerShadowColor | elevation | string | var(--shadow) | var(--shadow) |
variant.filled.contentColor | color | string | {color.role.onPrimary} | var(--on-primary) |
variant.filled.defaultElevation | elevation | string | level0 | level0 |
variant.filled.disabledElevation | elevation | string | level0 | level0 |
variant.filled.focusedElevation | elevation | string | level0 | level0 |
variant.filled.hoveredElevation | elevation | string | level1 | level1 |
variant.filled.iconColor | color | string | {component.button.variant.filled.contentColor} | var(--on-primary) |
variant.filled.pressedElevation | elevation | string | level0 | level0 |
variant.filledTonal.containerColor | color | string | {color.role.secondaryContainer} | var(--secondary-container) |
variant.filledTonal.containerShadowColor | elevation | string | var(--shadow) | var(--shadow) |
variant.filledTonal.contentColor | color | string | {color.role.onSecondaryContainer} | var(--on-secondary-container) |
variant.filledTonal.defaultElevation | elevation | string | level0 | level0 |
variant.filledTonal.disabledElevation | elevation | string | level0 | level0 |
variant.filledTonal.focusedElevation | elevation | string | level0 | level0 |
variant.filledTonal.hoveredElevation | elevation | string | level1 | level1 |
variant.filledTonal.iconColor | color | string | {component.button.variant.filledTonal.contentColor} | var(--on-secondary-container) |
variant.filledTonal.pressedElevation | elevation | string | level0 | level0 |
variant.outlined.containerColor | color | string | transparent | transparent |
variant.outlined.contentColor | color | string | {color.role.onSurfaceVariant} | var(--on-surface-variant) |
variant.outlined.defaultElevation | elevation | string | level0 | level0 |
variant.outlined.disabledElevation | elevation | string | level0 | level0 |
variant.outlined.focusedElevation | elevation | string | level0 | level0 |
variant.outlined.hoveredElevation | elevation | string | level0 | level0 |
variant.outlined.iconColor | color | string | {component.button.variant.outlined.contentColor} | var(--on-surface-variant) |
variant.outlined.outlineColor | color | string | {color.role.outlineVariant} | var(--outline-variant) |
variant.outlined.outlineWidth | size | dimension | 1px | 1px |
variant.outlined.pressedElevation | elevation | string | level0 | level0 |
variant.text.containerColor | color | string | transparent | transparent |
variant.text.contentColor | color | string | {color.role.primary} | var(--primary) |
variant.text.defaultElevation | elevation | string | level0 | level0 |
variant.text.disabledElevation | elevation | string | level0 | level0 |
variant.text.focusedElevation | elevation | string | level0 | level0 |
variant.text.hoveredElevation | elevation | string | level0 | level0 |
variant.text.iconColor | color | string | {component.button.variant.text.contentColor} | var(--primary) |
variant.text.pressedElevation | elevation | string | level0 | level0 |
For source disagreements and web adaptations, see Material fidelity and web adaptation near the end of this page. In particular, disabled presentation, the current Small default, Square shapes, and the Android-only precision-pointer policy all have explicit reconciliations rather than hidden overrides.
Usage and variant hierarchy
Material's Button family has five common variants. Choose the variant for the action's emphasis; do not choose one only because its decoration looks more prominent.
| Public component | Material guidance | Typical use |
|---|---|---|
Button | Filled, high emphasis | Important final or primary actions such as Save, Confirm, or Join now |
FilledTonalButton | Middle ground between filled and outlined | A significant or lower-priority action that needs more emphasis than an outline |
OutlinedButton | Medium emphasis | Important but non-primary alternatives such as Back or Cancel |
TextButton | Lowest emphasis | Supplementary and low-priority actions, especially alongside stronger actions |
ElevatedButton | Tonal-style container with elevation | Use when the action needs visual separation from a patterned or difficult background, not simply to make it look more important |
import { Button, ElevatedButton, FilledTonalButton, OutlinedButton, TextButton } from '@m3-ui/ui';
export function ButtonVariantsLiveExample() {
return (
<div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12 }}>
<Button>Save</Button>
<FilledTonalButton>Next</FilledTonalButton>
<OutlinedButton>Back</OutlinedButton>
<TextButton>Learn more</TextButton>
<ElevatedButton>Open on image</ElevatedButton>
</div>
);
}Labels
Material guidance says a Button label should describe the action that will occur. Prefer concise action wording such as Save, Confirm, Next, or Back over labels that do not explain the result.
Icons
An icon is optional. Use it when it helps communicate the action or draws useful attention to it; keep visible text as the stable action label.
import { Button, FilledTonalButton, TextButton } from '@m3-ui/ui';
export function ButtonIconsLiveExample() {
return (
<div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12 }}>
<Button startIcon={<span>+</span>}>Create</Button>
<FilledTonalButton startIcon={<span>↗</span>}>Share</FilledTonalButton>
<TextButton endIcon={<span>→</span>}>Learn more</TextButton>
</div>
);
}Do and don't
- Choose Filled, Tonal, Outlined, Text, or Elevated according to the action emphasis.
- Use a label that describes the action that will happen when the Button is activated.
- Add an icon only when it helps clarify the action; keep the label as the primary content.
- Use Elevated when the Button needs separation from a patterned or visually difficult background.
- Do not use Elevated only to make an action look more important; Material recommends limiting elevation to avoid excessive shadow.
- Do not give actions with different priorities the same emphasis when that obscures the action hierarchy.
- Do not choose a variant only for its color or decoration; the variant should communicate action priority and context.
- Use
onPressand let React Aria own keyboard, pointer, focus-visible, and disabled semantics. - Use
size,buttonShapesForSize(), variant components, and theme tokens instead of copying padding, radius, elevation, or state colors. - Use a link or anchor for navigation; use Button for an action.
- Use
IconButtonwhen the action is intentionally icon-only, and provide an accessible label.
- Do not attach an independent click handler to child content inside a Button; the root Button must remain the single action owner.
- Do not override geometry or state presentation in application CSS to imitate another Button variant.
- Do not infer Android precision-pointer compaction from
pointer: fine, hover capability, or the current pointer event.
Expressive sizes
The public size API exposes extraSmall, small, medium, large, and extraLarge. Size changes the Material geometry, icon scale, spacing, and label type role as one contract; avoid changing those dimensions independently.
import { Button } from '@m3-ui/ui';
export function ButtonSizesLiveExample() {
return (
<div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12 }}>
<Button size="extraSmall">Extra small</Button>
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>
<Button size="extraLarge">Extra large</Button>
</div>
);
}Omitting size uses small, matching the current Material 3 Design Kit component-set default. The legacy baseline remains in the token source as audited Compose-classic / Material-Web-runtime evidence; it is not the public React default.
Round and Square shapes
The current Material 3 Design Kit publishes both Round and Square Button types for every expressive size. Use the audited helper instead of copying corner radii.
import { Button, buttonShapesForSize } from '@m3-ui/ui';
export function ButtonShapesLiveExample() {
return (
<div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12 }}>
<Button size="medium" shapes={buttonShapesForSize('medium')}>
Round
</Button>
<Button size="medium" shapes={buttonShapesForSize('medium', 'square')}>
Square
</Button>
</div>
);
}buttonShapesForSize(size) uses Round. Pass 'square' as the second argument for the size-specific Square container. Both forms keep the audited pressed-shape target for that size.
Behavior and states
React Aria owns the current browser interaction state. Material tokens, ripple, shape, color, elevation, and motion own presentation for hover, keyboard focus, press, and disabled state.
import { Button, OutlinedButton } from '@m3-ui/ui';
export function ButtonStatesLiveExample() {
return (
<div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12 }}>
<Button>Enabled</Button>
<Button isDisabled>Disabled</Button>
<OutlinedButton>Keyboard focusable</OutlinedButton>
</div>
);
}The Button is the single action owner. Do not add a second press/click engine inside the content tree.
Accessibility
Button uses browser button semantics with keyboard activation, disabled handling, and focus-visible behavior supplied by React Aria. Use visible action text that describes the result of activation.
startIcon and endIcon are decorative slots and are kept out of the accessibility tree so the visible action label remains the stable accessible name. When an action must be icon-only, use the dedicated Icon button family and provide an accessible label.
API reference
Button
Button(props: ButtonProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
endIcon | ReactNode | — | — | @m3-ui/ui |
shapes | ButtonShapes | undefined | — | Optional normal/pressed container shapes. Supplying shapes enables the Material expressive pressed-shape morph while preserving RAC interactions. | @m3-ui/ui |
size | ButtonSize | undefined | — | Material 3 Button size. Defaults to `small`, matching the current Material 3 Design Kit component-set default and audited current Small size tokens. | @m3-ui/ui |
startIcon | ReactNode | — | — | @m3-ui/ui |
Inherited React / web props (112)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-controls | string | undefined | — | Identifies the element (or elements) whose contents or presence are controlled by the current element. | react-aria |
aria-current | boolean | "true" | "false" | "page" | "step" | "location" | "date" | "time" | undefined | — | Indicates whether this element represents the current item within a container or set of related elements. | react-aria |
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-disabled | boolean | "true" | "false" | undefined | — | Indicates whether the element is disabled to users of assistive technology. | react-aria |
aria-expanded | boolean | "true" | "false" | undefined | — | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. | react-aria |
aria-haspopup | boolean | "true" | "false" | "dialog" | "grid" | "listbox" | "menu" | "tree" | undefined | — | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. | react-aria |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
aria-pressed | boolean | "true" | "false" | "mixed" | undefined | — | Indicates the current "pressed" state of toggle buttons. | react-aria |
autoFocus | boolean | undefined | — | Whether the element should receive focus on render. | @react-types/shared |
children | ChildrenOrFunction<ButtonRenderProps> | — | The children of the component. A function may be provided to alter the children based on component state. | react-aria-components |
className | ClassNameOrFunction<ButtonRenderProps> | undefined | 'react-aria-Button' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
dir | string | undefined | — | — | @react-types/shared |
excludeFromTabOrder | boolean | undefined | — | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. | @react-types/shared |
form | string | undefined | — | The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form). | react-aria |
formAction | string | ((formData: FormData) => void | Promise<void>) | undefined | — | The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner. | react-aria |
formEncType | string | undefined | — | Indicates how to encode the form data that is submitted. | react-aria |
formMethod | string | undefined | — | Indicates the HTTP method used to submit the form. | react-aria |
formNoValidate | boolean | undefined | — | Indicates that the form is not to be validated when it is submitted. | react-aria |
formTarget | string | undefined | — | Overrides the target attribute of the button's form owner. | react-aria |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
isDisabled | boolean | undefined | — | Whether the button is disabled. | react-aria |
isPending | boolean | undefined | — | Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers. | react-aria-components |
lang | string | undefined | — | — | @react-types/shared |
name | string | undefined | — | Submitted as a pair with the button's value as part of the form data. | react-aria |
onAnimationEnd | AnimationEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onBlur | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. | @react-types/shared |
onClick | ((e: MouseEvent<FocusableElement>) => void) | undefined | — | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onFocus | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. | @react-types/shared |
onFocusChange | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onHoverChange | ((isHovering: boolean) => void) | undefined | — | Handler that is called when the hover state changes. | @react-types/shared |
onHoverEnd | ((e: HoverEvent) => void) | undefined | — | Handler that is called when a hover interaction ends. | @react-types/shared |
onHoverStart | ((e: HoverEvent) => void) | undefined | — | Handler that is called when a hover interaction starts. | @react-types/shared |
onKeyDown | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. | @react-types/shared |
onKeyUp | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onPress | ((e: PressEvent) => void) | undefined | — | Handler that is called when the press is released over the target. | @react-types/shared |
onPressChange | ((isPressed: boolean) => void) | undefined | — | Handler that is called when the press state changes. | @react-types/shared |
onPressEnd | ((e: PressEvent) => void) | undefined | — | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. | @react-types/shared |
onPressStart | ((e: PressEvent) => void) | undefined | — | Handler that is called when a press interaction starts. | @react-types/shared |
onPressUp | ((e: PressEvent) => void) | undefined | — | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. | @react-types/shared |
onScroll | UIEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLButtonElement> | undefined | — | — | @react-types/shared |
preventFocusOnPress | boolean | undefined | — | Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control. | react-aria |
render | DOMRenderFunction<"button", ButtonRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
style | StyleOrFunction<ButtonRenderProps> | undefined | — | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
type | "button" | "submit" | "reset" | undefined | 'button' | The behavior of the button when used in an HTML form. | react-aria |
value | string | undefined | — | The value associated with the button's name when it's submitted with the form data. | react-aria |
Source: packages/ui/src/components/Button/Button.tsx:117
Material fidelity and web adaptation
- Family
- Buttons
- Provenance
- spec: Material 3 overview · spec: Material 3 specification · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- Button · ElevatedButton · FilledTonalButton · OutlinedButton · TextButton
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implemented with canonical Material tokens, all five Material button variants, expressive size helpers, icon slots, disabled treatment, ripple/state layers, and optional pressed-shape morphing.
- Behavior fidelity
- adapted: React Aria owns browser button semantics and pointer, keyboard, focus, and hover interaction state. Material tokens remain authoritative for geometry, typography, color, elevation, shape, and state-layer presentation.
- Semantics fidelity
- adapted: React Aria owns browser button semantics and pointer, keyboard, focus, and hover interaction state. Material tokens remain authoritative for geometry, typography, color, elevation, shape, and state-layer presentation.
- Adaptations
- React Aria owns browser button semantics and pointer, keyboard, focus, and hover interaction state. Material tokens remain authoritative for geometry, typography, color, elevation, shape, and state-layer presentation.
Material 3 is authoritative for Button hierarchy, visual variants, shape, state treatment, and expressive sizing. Browser/React Aria semantics intentionally supply native web activation, pointer hover, keyboard focus, and event lifecycles rather than mechanically porting Compose runtime primitives.
The current Compose precision-pointer policy is intentionally not mapped to a CSS media query: its Android trigger depends on an enabled feature flag and physical keyboard + mouse device inventory, which is not equivalent to pointer: fine on the web. Choose size explicitly when a product needs a denser web control policy.
Related components
- Icon button — compact icon-only actions and icon toggles.
- FAB — prominent screen-level actions.
- Toggle button — persistent pressed/selected actions.
- Button group — grouped actions or connected selection.