# Button

> A button or a component that looks like a button.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/button)

<ComponentPreview name="p-button-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/button.json" />

## Usage

```svelte
<script lang="ts">
  import { Button } from "$lib/components/ui/button/index.js";
</script>

<Button>Button</Button>
```

## Link

Pass `href` to render a semantic link with the same styles.

```svelte
<Button href="/login">Login</Button>
```

## API Reference

### Button

A button component with variant, size, and loading states. Native attributes pass to the rendered
element.

| Prop       | Type                                                                                                      | Default     | Description                                                       |
| ---------- | --------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
| `variant`  | `"default" \| "destructive" \| "destructive-outline" \| "ghost" \| "link" \| "outline" \| "secondary"`    | `"default"` | Controls the button styling                                       |
| `size`     | `"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs" \| "lg" \| "sm" \| "xl" \| "xs"` | `"default"` | Controls the button size                                          |
| `loading`  | `boolean`                                                                                                 | `false`     | Shows a spinner and forces disabled button behavior while loading |
| `href`     | `string`                                                                                                  | —           | Renders a semantic link with the button styles                    |
| `target`   | `string`                                                                                                  | —           | Sets the link browsing context when `href` is present             |
| `rel`      | `string`                                                                                                  | —           | Sets the link relationship when `href` is present                 |
| `download` | `boolean \| string`                                                                                       | —           | Downloads the linked resource when `href` is present              |
| `as`       | `keyof HTMLElementTagNameMap`                                                                             | `"button"`  | Renders a different non-link element                              |

When `loading` is `true`, the component:

- Renders a spinner (`data-slot="button-loading-indicator"`)
- Adds `data-loading` on the button root
- Forces the native `disabled` attribute for buttons
- Sets `aria-disabled="true"`
- Preserves button width because it keeps the child content mounted and hides it visually

See the [Shards Button API](https://shardsui.com/svelte/button) for keyboard and disabled behavior.

## Examples

### Default

<ComponentPreview name="p-button-1" />

### Outline

<ComponentPreview name="p-button-2" />

### Secondary

<ComponentPreview name="p-button-3" />

### Destructive

<ComponentPreview name="p-button-4" />

### Destructive Outline

<ComponentPreview name="p-button-5" />

### Ghost

<ComponentPreview name="p-button-6" />

### Link

<ComponentPreview name="p-button-7" />

### Extra-small Size

<ComponentPreview name="p-button-8" />

### Small Size

<ComponentPreview name="p-button-9" />

### Large Size

<ComponentPreview name="p-button-10" />

### Extra-large Size

<ComponentPreview name="p-button-11" />

### Disabled

<ComponentPreview name="p-button-12" />

### Icon

<ComponentPreview name="p-button-13" />

### Icon Small Size

<ComponentPreview name="p-button-14" />

### Icon Large Size

<ComponentPreview name="p-button-15" />

### With Icon

<ComponentPreview name="p-button-16" />

### With Link

<ComponentPreview name="p-button-17" />

### Loading (Built-in Prop)

<ComponentPreview name="p-button-41" />

### Loading (Custom Composition)

<ComponentPreview name="p-button-18" />