Button

Buttons trigger actions, confirm intent, and surface secondary options.

Variants

Use primary for the main action and secondary for supporting actions. default, outline, dashed, transparent, link, and none cover quieter or borderless treatments.

Sizes

The size scale is shared across text buttons, icon buttons, and icon-plus-label buttons so controls can stay visually aligned in dense CP interfaces.

Icons

Slot icons with <Icon slot="start"> / slot="end" — prepend, append, both, or icon-only. Let Button own glyph size via --pk-btn-icon-size; do not size the icon yourself.

Icon-Only Sizes

Icon-only buttons (no label) are square by default — hit box matches the size height — so they align in table action rows. Add the boolean icon prop when you want a padless control that hugs the glyph (dense × / ⋯). groupTrigger stays a narrow disclosure end-cap either way.

Loading

Loading buttons should preserve their footprint and communicate progress without shifting nearby controls.

Disabled and Links

Use disabled buttons for unavailable actions, and the link variant when the action navigates.

API

Slots

Name	Description
(default)	Button label
start	Leading icon or prefix
end	Trailing icon or suffix

Props

Name	Description
ariaLabel	Accessible name — wins over title when both are set. Type string | null Default null
disabled	Disables the control and blocks activation. Type boolean Default false
form	HTML form owner id — same as native <button form="…">. Needed when the submit control lives outside the <form> (e.g. dialog footer). Type string | undefined
groupTrigger	Compact chevron-only trigger for grouped split actions — Craft .menubtn. Not a variant or size: set this boolean on the disclosure end-cap in a split group. Hides label/icons and draws a CSS ::after chevron (0.4375rem, 2px borders). Inherits variant/size from sibling buttons; inline padding narrows to 8px. Do not pass a chevron icon — use icon + a start-slot icon for a padless square control. Type boolean Default false
href	When set, renders as an anchor instead of a button. Type string | undefined
icon	Compact icon density: padless box that hugs the glyph (no square hit target). Prefer default icon-only usage for action rows — without this flag, icon-only buttons are square (width/height = size height) with the glyph from --pk-btn-icon-size. Use icon for dense × / ⋯ in cells. For one-off dimensions use size="none" and set --pk-btn-* on the host. Type boolean Default false
loading	Shows an inline spinner and prevents activation while busy. Type boolean Default false
name	Native name when used as a submit/reset control. Type string | undefined
rel	Anchor rel when href is set. Type string | undefined
size	Shared CP size scale (xxs … xl); none skips presets for host token overrides. Type PkButtonSize Default default
spinnerSize	Override loading spinner size. When unset, derived from size via getButtonSpinnerSize — same defaults as v1 Button (xxs/xs → xxs, lg/xl → sm, else xs). Formie New Form passes xs on size="lg" so the ring stays size-4 (1rem), not sm (1.5rem). Type PkSpinnerSize | undefined
spinnerTone	Loading spinner tone. Defaults from the button variant when unset. Type PkSpinnerTone | undefined
spinnerVariant	Loading spinner visual style. Defaults from the button variant when unset. Type PkSpinnerVariant | undefined
target	Anchor target when href is set. Type string | undefined
title	Accessible name for icon-only / unlabeled controls. Applied as aria-label — never as HTML title (no native hover tooltip). Prefer the aria-label attribute when setting from markup; title remains as a concise alias for the same accessible name. Type string
type	Native button type — ignored when href is set. Type 'button' | 'submit' | 'reset' Default button
value	Native value when used as a submit control. Type string | undefined
variant	Visual treatment — filled, outline, link, etc. Type PkButtonVariant Default default
withCaret	Shows a disclosure caret after the label. Type boolean Default false

CSS Custom Properties

Name	Description
--pk-btn-caret-size	Built-in caret glyph size. Default var(--pk-btn-caret-size-default)
--pk-btn-fill	Background fill (filled variants).
--pk-btn-fill-active	Active / pressed fill.
--pk-btn-fill-hover	Hover fill.
--pk-btn-font	Label font size. Default var(--pk-btn-font-default)
--pk-btn-height	Control height (also min-height). Default var(--pk-btn-height-default)
--pk-btn-icon-gap	Gap between icons and label. Default var(--pk-btn-icon-gap-default)
--pk-btn-icon-size	Start/end slot glyph size. Default var(--pk-btn-icon-size-default)
--pk-btn-on	Foreground color on filled variants.
--pk-btn-padding-block	Vertical padding override. Default 0
--pk-btn-padding-inline	Horizontal padding. Default var(--pk-btn-padding-inline-default)
--pk-btn-radius	Border radius. Default var(--pk-btn-radius-default)

CSS Parts

Name	Description	CSS selector
base	The native button / link element	::part(base)

Dependencies

This component registers the following elements when it loads.

Name	Description
pk-spinner	Loading indicator rendered while loading is set.