Button

See all buttons in the buttons page.

Overview

The <Button /> component is a versatile UI element used for triggering actions, navigating between pages, and providing interactive functionality. It supports multiple visual variants, sizes, icon placement, and can render as either a button or link element.

Basic Usage

Default Button

<Button>Click me</Button>

Button with Variant

<Button variant="accent" size="md">
  Get Started
</Button>

As a Link

<Button isLink href="/docs" variant="outline">
  View Documentation
</Button>

API Reference

Props

Prop	Type	Default	Description
variant	string	"default"	Visual style variant
size	string	"base"	Button size
iconOnly	boolean	false	Renders icon-only button
gap	string	-	Spacing between icon and text
isLink	boolean	false	Renders as <a> instead of <button>
href	string	-	Link destination (automatically sets isLink=true)
class	string	-	Additional CSS classes

Slots

Slot	Description
default	Button text content
icon	Icon for icon-only buttons
left-icon	Icon positioned before text
right-icon	Icon positioned after text

Variants

The component supports multiple visual styles for different use cases:

Filled Variants

<Button variant="default">Default</Button>
<Button variant="accent">Accent</Button>
<Button variant="muted">Muted</Button>
<Button variant="info">Info</Button>
<Button variant="success">Success</Button>
<Button variant="warning">Warning</Button>
<Button variant="danger">Danger</Button>

Examples

Outline Variants

<Button variant="outline">Outline</Button>
<Button variant="outline-accent">Outline Accent</Button>
<Button variant="outline-info">Outline Info</Button>
<Button variant="outline-success">Outline Success</Button>
<Button variant="outline-warning">Outline Warning</Button>
<Button variant="outline-danger">Outline Danger</Button>

Examples

Sizes

Available size options from smallest to largest:

<Button size="mini">Mini</Button>
<Button size="xxs">XXS</Button>
<Button size="xs">XS</Button>
<Button size="sm">Small</Button>
<Button size="base">Base</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">XL</Button>

Examples

Icon Usage

Icon-Only Buttons

Perfect for toolbars, compact interfaces, or when space is limited:

<Button variant="default" size="md" iconOnly>
  <Plus slot="icon" size="base" />
</Button>

Examples

Buttons with Icons and Text

Left Icon

<Button variant="accent">
  <Plus slot="left-icon" />
  Add Item
</Button>

Right Icon

<Button variant="success">
  Save Changes
  <Plus slot="right-icon" />
</Button>

Both Icons

<Button variant="info">
  <Plus slot="left-icon" />
  Process
  <Plus slot="right-icon" />
</Button>

Examples

Icon Spacing

Control the gap between icons and text using the gap prop:

<!-- Tight spacing -->
<Button variant="accent" gap="xs">
  <Plus slot="left-icon" />
  Compact
</Button>

<!-- Default spacing -->
<Button variant="accent" gap="sm">
  <Plus slot="left-icon" />
  Normal
</Button>

<!-- Loose spacing -->
<Button variant="accent" gap="lg">
  <Plus slot="left-icon" />
  Spacious
</Button>

Available gap sizes: xs, sm, base, md, lg

Button vs Link

When to use each:

Use <button> (default) for:

• Form submissions
• Triggering JavaScript actions
• Opening modals or dropdowns
• Any action that doesn’t navigate

Use <a> (with isLink or href) for:

• Navigation between pages
• External links
• Downloadable files
• Anchoring to page sections

Implementation

Explicit Link Mode

<Button isLink href="/pricing" variant="accent">
  View Pricing
</Button>

Automatic Link Mode (when href is provided)

<Button href="/login" variant="outline">
  Login
</Button>

External Links

<Button href="https://github.com/yourrepo" variant="muted">
  View on GitHub
</Button>

Customization

Custom Classes

Extend the button’s styling with additional CSS classes:

<Button 
  variant="warning" 
  class="uppercase tracking-wide font-bold"
>
  Custom Style
</Button>

Disabled State

<Button variant="accent" disabled>
  Disabled Button
</Button>

Loading State

<Button variant="accent" class="opacity-50 cursor-not-allowed">
  <Plus slot="left-icon" class="animate-spin" />
  Loading...
</Button>

Common Patterns

Call-to-Action Buttons

<Button variant="accent" size="lg">
  Get Started Free
</Button>

Form Actions

<div class="flex gap-2">
  <Button type="submit" variant="accent">
    Save
  </Button>
  <Button type="button" variant="outline">
    Cancel
  </Button>
</div>

Navigation

<Button href="/dashboard" variant="muted">
  <Plus slot="left-icon" />
  Back to Dashboard
</Button>

Toolbar Actions

<div class="flex gap-1">
  <Button variant="outline" size="sm" iconOnly>
    <Plus slot="icon" />
  </Button>
  <Button variant="outline" size="sm" iconOnly>
    <Plus slot="icon" />
  </Button>
  <Button variant="outline" size="sm" iconOnly>
    <Plus slot="icon" />
  </Button>
</div>

Accessibility

The Button component includes built-in accessibility features:

• Proper focus management with visible focus rings
• Semantic HTML (<button> vs <a> based on usage)
• Support for screen readers
• Keyboard navigation support

Best Practices

1. Use descriptive text - Avoid generic labels like “Click here”
2. Provide context for icon-only buttons - Consider adding aria-label
3. Use appropriate variants - Match visual style to action importance
4. Maintain consistent sizing - Use similar sizes for related actions
5. Test keyboard navigation - Ensure all buttons are reachable via Tab

Migration Guide

If migrating from a previous button implementation:

1. Replace className prop with class
2. Use isLink instead of as="a"
3. Icon placement now uses slots instead of props
4. Size names may have changed - check the available options above