Button

Displays a button or a component that looks like a button.

<Button>Button</Button>

Installation

pnpm dlx cubix@latest add button --base aria

Usage

Import

import { Button } from "@/components/cubix/button"

Example

<Button variant="outline">Button</Button>

Examples

Variants

<Button>Default</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

Sizes

<Button size="xs">Extra small</Button>
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button variant="outline" size="icon-xs" aria-label="Extra small icon">
  <MailIcon />
</Button>
<Button variant="outline" size="icon-sm" aria-label="Small icon">
  <MailIcon />
</Button>
<Button variant="outline" size="icon" aria-label="Icon button">
  <MailIcon />
</Button>
<Button variant="outline" size="icon-lg" aria-label="Large icon">
  <MailIcon />
</Button>

With icon

Render an icon inside the button. Use data-icon="inline-start" and data-icon="inline-end" so padding follows reading direction in LTR and RTL.

<Button>
  <MailIcon data-icon="inline-start" />
  Login with Email
</Button>

Icon only

<Button variant="outline" size="icon" aria-label="Send email">
  <ArrowRightIcon />
</Button>

Loading

Disable the button and compose a spinner while an async action is in flight. Click the button below to try it:

<Button disabled>
  <LoaderIcon data-icon="inline-start" className="animate-spin" />
  Saving...
</Button>

If you prefer full control, compose the spinner yourself:

<Button disabled>
  <LoaderIcon data-icon="inline-start" className="animate-spin" />
  Please wait
</Button>

As link

Use render (Base UI / React Aria) or asChild (Radix) to render a Next.js <Link /> with button styles. On Base UI pass nativeButton={false}.

Go to Docs

<Button nativeButton={false} render={<Link href="/docs" />}>
  Go to Docs
</Button>

Custom styling

Every prop accepts a className merged with the shipped cn helper:

<Button variant="outline" className="rounded-full px-6 text-base">
  Fully rounded
</Button>

Invalid

Set aria-invalid to switch to destructive border and ring styles - no extra prop needed:

<Button aria-invalid>Invalid</Button>
<Button variant="outline" aria-invalid>
  Invalid
</Button>

Disabled

<Button disabled>Disabled</Button>

RTL

To enable RTL support, see the Direction guide. Icon padding uses inline-start / inline-end so it stays correct under dir="rtl".

<div dir="rtl" lang="fa" className="flex flex-wrap justify-center gap-2">
  <Button>ادامه</Button>
  <Button variant="secondary">انصراف</Button>
  <Button variant="outline">
    <MailIcon data-icon="inline-start" />
    ایمیل
  </Button>
  <Button>
    ادامه
    <ArrowLeftIcon data-icon="inline-end" />
  </Button>
</div>

API Reference

Note: Mark icons and spinners with data-icon so spacing follows reading direction. Icon-only buttons need an aria-label.

Props

Prop	Type	Default	Description
variant	"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link"	"default"	The visual style of the button.
size	"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"	"default"	The size of the button.
render	React.ReactElement	-	Base UI / React Aria: render the button as another element, such as a Next.js Link. Pass nativeButton={false} on Base UI when that element is not a native button.
asChild	boolean	-	Radix: merge props onto the child element instead of rendering a button.
nativeButton	boolean	true	Base UI: set to false when render points at a non-button host such as an anchor or Link.
disabled	boolean	false	Disables the button and prevents interaction.
aria-invalid	boolean	-	Marks the button as invalid and applies destructive border and ring styles.
type	"button" \| "submit" \| "reset"	"button"	Native button type. Defaults to button so it does not submit enclosing forms.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

Variants

Prop	Type	Default	Description
default	-	-	Solid primary button. The main call-to-action style.
secondary	-	-	A softer alternative to the default variant for secondary actions.
destructive	-	-	For destructive actions such as deleting data.
outline	-	-	Bordered button that pairs well with secondary or ghost buttons.
ghost	-	-	No background until hover. Ideal for toolbars and menus.
link	-	-	Looks like a link but behaves like a button.

Sizes

Prop	Type	Default	Description
xs	h-6	-	Extra-compact control for dense chrome.
sm	h-7	-	Compact button for dense UIs.
default	h-8	-	Standard height button.
lg	h-9	-	Large button for prominent actions.
icon-xs	size-6	-	Extra-small square button for icon-only actions.
icon-sm	size-7	-	Small square button for icon-only actions.
icon	size-8	-	Square button for icon-only actions.
icon-lg	size-9	-	Large square button for icon-only actions.