In an icon size only the marks are visible. The label stays in the content, hidden visually, and names the Button for assistive technology, so write the action as the label instead of adding aria-label.
The icon itself is never used as the accessible name. An unnamed Button emits a tp-diagnostic warning.
Icon only
Default density
Compact density
Restart from the initial state
Show the copyable source
icon-xs, icon-sm, icon and icon-lg make square Buttons that match the heights of xs, sm, the default and lg, so an icon action lines up with text Buttons of the same size.
Icon sizes
Default density
Compact density
Restart from the initial state
Show the copyable source
Use the icon-start and icon-end slots for custom marks, and mark them decorative. loading-position composes the library’s Spinner and exposes busy semantics without disabling the action.
For common single-mark cases, set icon with iconPosition, or set loadingPosition to compose the shared Spinner. leading and trailing are logical positions that follow writing direction.
Mark sources use this precedence: loadingPosition, then icon, then the slots. Clearing a higher-priority property restores the next source without removing slotted content. The convenience icon is decorative because the label names the control; custom decorative marks should use aria-hidden="true".
The Spinner inherits the Button’s resolved text color in every variant and state. Loading does not set disabled; set disabled and, when appropriate, focusableWhenDisabled explicitly for a pending operation.
Marks and loading
Default density
Compact density
Restart from the initial state
Show the copyable source
←
Back
Next
→Saving
←
Back
Next
→Saving
<tp-button variant="outline">
<span slot="icon-start" aria-hidden="true">←</span>
Back
</tp-button>
<tp-button>
Next
<span slot="icon-end" aria-hidden="true">→</span>
</tp-button>
<tp-button loading-position="leading">Saving</tp-button>
A Button in a text size whose label is empty shows only its marks, with one gap between them and the icon padding at both edges, as in a trigger that pairs an icon with a chevron. Nothing visible names it, so give it an aria-label. Text added to the label later shows the label again.
Icon and chevron
Default density
Compact density
Restart from the initial state
Show the copyable source
Set href and the Button renders a native anchor while keeping any visual variant. target, rel and download are forwarded.
Link hosting ignores type, name, value, and nativeAction; removing href restores action behavior.
variant="link" alone changes appearance only, so an action can still use link styling without becoming navigation. A disabled link retains its href for inspection but prevents navigation; focusableWhenDisabled controls whether it remains in the tab order.
As a link
Default density
Compact density
Restart from the initial state
Show the copyable source
Read the guideDownload report
Read the guideDownload report
<tp-button href="#links">Read the guide</tp-button>
<tp-button variant="outline" href="#links" download="report.csv">Download report</tp-button>
Forms
The default type is button, so a Button never submits by accident. A named submit Button contributes its name and value as the submitter.
Each completed pointer or keyboard gesture activates at most once. A consumer may cancel the initiating click with preventDefault() before a submit or reset action runs.
Form actions
Default density
Compact density
Restart from the initial state
Show the copyable source
focusable-when-disabled keeps a disabled Button in the tab order, exposing aria-disabled without allowing activation.
Part customization
partContracts configures each of button, button-label, button-leading-mark, and button-trailing-mark. Contracts accept hostProperties, classHook, styleHook, content, elementReference, and renderDelegate. The reference receives the actual rendered element and becomes null when it is replaced or disconnected. focus(), blur(), and click() follow the actual control.
A delegate must apply its supplied bind to the semantic host. A substituted action host retains Button semantics and receives synthesized Enter/Space activation. A Button with href requires an actual anchor; a non-anchor delegate emits a diagnostic and falls back to the native anchor. Owned action type, disabled/focus policy, ARIA, state and part markers, and the hidden state of the label and the marks survive neutral property and appearance overrides.
Consumer handlers run before the corresponding Button handler. Call event.preventComponentHandling() to suppress that component action while preserving native default prevention as a separate channel. preventDefault() still cancels a queued submit/reset. Disabled controls block activation before consumer click handlers. For a link, suppressing its click action also prevents navigation.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptiontypetypeButtonType'button'The form action: submit and reset act on the owning form; the default button never submits by accident.variantvariant'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link''default'Visual emphasis only; href, not the link treatment, makes the Button navigate.sizesize'xs' | 'sm' | 'default' | 'lg' | 'icon-xs' | 'icon-sm' | 'icon' | 'icon-lg''default'The control height; an icon size makes a square Button the height of the matching text size and shows only its marks.namenamestring''The name a submit Button contributes to the form data as the submitter.valuevaluestring''The value a submit Button contributes under its name.icon-positioniconPositionLogicalPosition'leading'The side of the label that icon takes, following the writing direction.loading-positionloadingPositionLogicalPosition | nullnullShows a Spinner on that side and marks the Button busy without disabling it.hrefhrefstring | nullnullMakes the Button a native link to this address, keeping its visual treatment.targettargetstring | nullnullThe browsing context a link Button opens in.relrelstring | nullnullThe relationship of a link Button's target to the current page.downloaddownloadstring | nullnullMakes a link Button download its target, optionally under this file name.native-actionnativeActionbooleantrueSet to false to render a non-native button host that still activates with Enter and Space.focusable-when-disabledfocusableWhenDisabledbooleanfalseKeeps a disabled Button in the tab order, announced as disabled and still unable to activate.aria-labelariaLabelstring | null—The accessible name when no visible label names the Button, as for an icon with a chevron.
Properties
PropertyTypeDefaultDescriptioniconIconDefinition | undefined—A decorative icon drawn as a mark beside the label; the label stays the accessible name.
Methods
MethodReturnsDescriptionfocus(options?)voidFocuses the rendered button or link.blur()voidRemoves focus from the rendered button or link.click()voidActivates the rendered button or link, as a pointer click would.
Slots
SlotDescriptiondefaultThe label. In an icon size it is hidden visually and still names the Button.icon-startA custom mark before the label, used when neither icon nor loadingPosition fills that side.icon-endA custom mark after the label, used when neither icon nor loadingPosition fills that side.
CSS parts
PartDescription::part(button)The native button or link: the target of focus, activation and the variant appearance.::part(button-label)The label; hidden visually in an icon size and when it has no content.::part(button-leading-mark)The mark before the label: the icon, the Spinner or the icon-start slot.::part(button-trailing-mark)The mark after the label: the icon, the Spinner or the icon-end slot.
Related
Components, widgets and patterns that use this one.