Button
A clickable action. color, variant and size are independent axes, with shape and fullWidth as modifiers.
'use client';
import { Button } from '@clerk/mosaic/components/button';
export default function ButtonExample() {
return (
<>
<Button>Save changes</Button>
<Button
variant='outline'
color='neutral'
>
Cancel
</Button>
<Button
variant='ghost'
color='negative'
>
Delete
</Button>
</>
);
}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
| Guidance | Practice |
|---|---|
| Do | Use SubmitButton for any action that waits on async work. In a form it submits; outside one, pass type='button' and onClick, as Confirmation does. |
| Do | Use Button for actions that finish at once, such as Cancel, Back or opening a dialog. |
| Do | In a view, hold the primary action pending until the next step renders. The rules are in the Views guide (mosaic guides inspect views). |
| Do | Use ProviderButton to sign in with a third-party provider. |
| Do | Pass focusableWhenDisabled when a button disables itself mid-interaction. |
| Do | Pass touchTarget={false} in a dense toolbar, where grown hit areas would overlap. |
| Don’t | Render 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
| Prop | Type | Description |
|---|---|---|
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' |
fullWidth | boolean | Stretches to the width of the container.Default: false |
touchTarget | boolean | Floors the hit area at the touch target size under a coarse pointer, without changing the rendered size. No effect on link.Default: true |
focusableWhenDisabled | boolean | Keeps 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
| Prop | Type | Description |
|---|---|---|
isPending | boolean | Makes the button inert and busy. After a short delay it fades the label and centers a spinner over it.Default: false |
pendingLabel | string | Accessible name for the spinner. Pass a localized string.Default: 'pending' |
spinDelay | SpinDelayOptions | delay before the spinner shows (default 150) and minDuration it stays (default 400). |
Examples
An action
<Button variant='outline' onClick={onCancel}>Cancel</Button>A submit
<SubmitButton isPending={form.isSubmitting}>Save</SubmitButton>An async action outside a form
<SubmitButton type='button' onClick={onRevoke} isPending={isRevoking}>
Revoke
</SubmitButton>