Button

kai-button

Handles every action in the UI, from the primary submit down to a quiet icon in a toolbar.

• Shadow DOM
• 5 variants
• Named + URL icons
• Emits kai-click

Preview

When to use

Any user-triggered action: submitting input, a toolbar action, confirming, dismissing. default is the primary action, subtle / ghost / outline the low-emphasis ones.

Usage

Put the label as light-DOM text inside the element. Set variant and size, add icon for a leading glyph, and listen for kai-click. For an icon-only button, drop the text, set size="icon", and name it with label.

<kai-button variant="subtle" size="icon" icon="mic" label="Voice input"></kai-button>
<kai-button variant="ghost" icon-trailing="chevron-down">High</kai-button>
<kai-button>Send</kai-button>

Examples

Variants

variant sets the emphasis: default (filled), subtle (muted text, hover tint), ghost, outline, destructive.

Code

Code

Code

Code

Sizes

Code

Code

Icon-only

Square sizes are icon / icon-sm; set label for the accessible name. icon takes a named icon, an image URL, or a data-URI.

Code

Trailing icon

icon-trailing sits after the label.

Code

Custom icon via slot

For a glyph the icon prop can’t name, slot it into slot="icon"; it wins over the prop. Keep label for the accessible name.

Code

Slots

The label is the default slot; icon is the one named seam:

Slot	Mode	Purpose
(default)	inject	The button's label. Omit it for an icon-only button (pair with `aria-label`).
icon	replace	A custom leading icon (any inline SVG, inherits `currentColor`). Wins over the `icon` prop.

<kai-button label="Ship">
  <svg slot="icon" viewBox="0 0 24 24" width="16" height="16"><!-- your glyph --></svg>
  Ship it
</kai-button>

Styling

The button is a single ::part, so radius, padding, color, and weight restyle from outside while variant / size stay the defaults.

Part	Purpose	Example
button	The button element. Restyle radius, padding, colors, or weight from outside; the `variant`/`size` props set the defaults.	kai-button::part(button) { border-radius: 9999px; font-weight: 600 }

Props

Property	Type	Default	Notes
theme	"light" | "dark" | "auto"	'auto'	Color mode (`auto` follows prefers-color-scheme).
variant	"default" | "subtle" | "ghost" | "outline" | "destructive"	'default'	Visual style. Defaults to `default` (filled).
size	"sm" | "md" | "lg" | "icon" | "icon-sm"	'md'	Size token: the square glyph-only sizes, or the text-button sizes. Defaults to `md`.
icon	string	—	Leading icon: a named icon (e.g. `"mic"`, `"plus"`), an image URL/data-URI, or plain text. Renders before any slotted label.
iconTrailing	string	—	Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance).
label	string	—	Accessible name for an icon-only button. Ignored when visible text is slotted -- the visible text wins.
disabled	boolean	false	Disable the button (non-interactive, dimmed).
full	boolean	false	Stretch the button to the full width of its container (a block button), e.g. a card CTA or a stacked action. Attribute: `full`.
align	"start" | "center" | "end"	'center'	Justify the button's content. Default is centered; combine with `full` for a full-width, left-aligned button.
type	"button" | "submit" | "reset"	'button'	Native button `type`. Defaults to `button` (so it never submits a form).

Events

Event	Detail	Notes
kai-click	—	The button was activated (pointer or keyboard). Carries no detail. The native `click` also bubbles (composed) for consumers who prefer it.

Methods

Method	Signature	Notes
focus	(options?: FocusOptions): void	Focus the inner `<button>` (host.focus() would focus the wrapper).
blur	(): void	Blur the inner `<button>`.
click	(): void	Programmatically activate the button. Runs the same path as a user click and fires kai-click. Forwarding to the inner button means `disabled` is respected automatically.

Composed from

This element wraps these SolidJS components — reach for them directly when you need finer control than the props expose.

Button

---

Need a hand? Report a bug Ask for help