icon | Icon | No | — | An optional icon to display in the button (agnostic Icon data). |
type | "button" | "submit" | "reset" | No | 'button' | The HTML button type attribute. Only applies when rendered as `<button>`. |
iconPosition | ButtonIconPosition | ButtonIconPositionAlias | No | 'start' | Logical icon position. The `left` and `right` aliases are retained for compatibility and resolve to `start` and `end` respectively. |
size | "small" | "large" | "xSmall" | "medium" | "xLarge" | No | 'medium' | Visual size; every option retains a 48px touch target. |
variant | ButtonVariant | ButtonVariantAlias | No | 'filled' | The button variant determines the style of the button. Aliases: 'primary' maps to 'filled', 'secondary' maps to 'tonal' |
disabled | boolean | No | false | Disables the button if set to true. |
edgeAligned | boolean | No | false | Aligns text-button content with the surrounding inline edge. Only applies to `text` variant buttons. |
stateColor | string | No | — | Colour token for the state layer, without the `--color-` prefix. Defaults to the token matching the resolved `variant`. Set it when the surface has been restyled through `className` -- a filled button repainted onto a container needs `on-primary-container`, not the `on-primary` the variant implies -- so the hover and press feedback keeps contrasting. |
loading | boolean | No | false | Blocks interaction and exposes the busy state while preserving the label. |
shape | "rounded" | "squared" | No | 'rounded' | The shape of the button defines whether it is squared or rounded. |
shapeFeedback | ButtonShapeFeedback | No | 'morph' | Shape feedback shown for accepted press and toggle interactions. |
transition | Transition | No | — | Motion transition shared by every framework for shape changes. |
toggleable | boolean | No | false | Enables the semantic pressed state and its visual treatment. |
pressed | boolean | No | — | Controlled pressed state. Framework adapters expose the matching change event (`onPressedChange` in React, `pressedChange` in Angular). |
defaultPressed | boolean | No | false | Initial pressed state when `pressed` is not controlled. |
label | string | No | — | Visible text content. Do not combine with `children`. |
children | ReactButtonChildren | No | — | Custom visible content. Use `aria-label` when it has no accessible text. |
className | string | ClassNameComponent<ButtonInterface> | Partial<Record<"button" | "label" | "stateLayer" | "touchTarget" | "icon", string>> | No | — | Classes or state-aware element classes applied through the shared style contract. |
onPressedChange | (pressed: boolean) => void | No | — | Notifies an accepted toggle-state request. |
href | string | No | — | Navigation destination; switches the native element from button to link. |
ref | Ref<HTMLButtonElement> | Ref<HTMLAnchorElement> | No | — | Ref forwarded to the native button element. Ref forwarded to the native anchor element. |
onClick | MouseEventHandler<HTMLButtonElement> | MouseEventHandler<HTMLAnchorElement> | No | — | Handles clicks accepted by the button interaction contract. Handles clicks accepted by the link interaction contract. |