Skip to content
Mosaic
On this page

Button

A clickable action. color, variant and size are independent axes, with shape and fullWidth as modifiers.

Use for

  • an action that finishes at once, such as Cancel or opening a dialog
  • an action that waits on async work, such as a form submit or a confirm, with SubmitButton
  • an icon-only action

Practices

GuidancePractice
DoUse SubmitButton for any action that waits on async work. In a form it submits; outside one, pass type='button' and onClick, as Confirmation does.
DoUse Button for actions that finish at once, such as Cancel, Back or opening a dialog.
DoIn a view, hold the primary action pending until the next step renders. The rules are in the Views guide (mosaic guides inspect views).
DoUse ProviderButton to sign in with a third-party provider.
DoPass focusableWhenDisabled when a button disables itself mid-interaction.
DoPass touchTarget={false} in a dense toolbar, where grown hit areas would overlap.
Don’tRender a spinner inside Button by hand. SubmitButton owns the spinner delay.

API reference

Button

Renders a button and forwards its ref. Defaults can come from ButtonContext.

Slot: cl-button

PropTypeDescription
color'primary' | 'neutral' | 'negative'primary, neutral or negative.Default: 'primary'
variant'filled' | 'outline' | 'ghost' | 'link'filled, outline, ghost or link.Default: 'filled'
size'xs' | 'sm' | 'md' | 'lg'xs, sm, md or lg.Default: 'md'
shape'default' | 'square' | 'circle'default, square or circle. Use square or circle for an icon-only button.Default: 'default'
fullWidthbooleanStretches to the width of the container.Default: false
touchTargetbooleanFloors the hit area at the touch target size under a coarse pointer, without changing the rendered size. No effect on link.Default: true
focusableWhenDisabledbooleanKeeps the button in the tab order while disabled, marked aria-disabled and inert to clicks.Default: false

SubmitButton

A Button for async actions. While isPending it goes inert and shows a spinner, keeping its width. Takes every Button prop; type defaults to submit, so pass type='button' outside a form.

Slot: cl-button

PropTypeDescription
isPendingbooleanMakes the button inert and busy. After a short delay it fades the label and centers a spinner over it.Default: false
pendingLabelstringAccessible name for the spinner. Pass a localized string.Default: 'pending'
spinDelaySpinDelayOptionsdelay before the spinner shows (default 150) and minDuration it stays (default 400).

Examples

An action

TSX
<Button variant='outline' onClick={onCancel}>Cancel</Button>

A submit

TSX
<SubmitButton isPending={form.isSubmitting}>Save</SubmitButton>

An async action outside a form

TSX
<SubmitButton type='button' onClick={onRevoke} isPending={isRevoking}>
  Revoke
</SubmitButton>