# Button

A clickable element that triggers an action when pressed.

## Usage

Use standalone.

```svelte
<Button {...props}>Label</Button>
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<button class="whole" {...rest} {type} {onclick} aria-disabled conditional aria-description conditional bind:this={element}>
  <span class="left" conditional>{left}</span>
  <span class="main">{children}</span>
  <span class="right" conditional>{right}</span>
</button>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `children*` | `Snippet` | - | Main label; receives the variant as its argument |
| `left` | `Snippet` | - | Content before the label |
| `right` | `Snippet` | - | Content after the label |
| `type` | `<enum>` | `"button"` | The button's `type` attribute |
| `onclick` | `MouseEventHandler` | - | Click handler; suppressed while `inactive` is set |
| `form` | `HTMLFormElement` | - | Form validated on click ([Details](/docs/form-controls#form-wide-validation)) |
| `inactive` | `string` | - | Non-empty reason marks `aria-disabled`, suppresses `onclick`, and forces the `inactive` variant (restored when cleared) |
| `attach` | `Attachment` | - | Svelte attachment on the root button |
| `element` | `HTMLButtonElement` | - | Bindable root element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Bindable variant |
`*` required. Other `HTMLButtonAttributes` are passed to `<button>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching in normal use, except that setting an `inactive` reason forces the variant to `inactive` while it is set and restores the prior variant when cleared.

### Default Class Name

`svs-button`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Button (`whole` `<button>`): `aria-disabled="true"` and `aria-description` from the `inactive` reason when `inactive` is set.

The managed inactive attributes are component-owned while inactive handling is active; activation is suppressed instead of using the native `disabled` attribute.

When `children` is an icon with no text, provide an accessible name by passing `aria-label` or `aria-labelledby` through the rest props so the button is not left unlabeled.

### Standards Basis

Button is built on a native `<button>`, so keyboard and assistive-technology support follows the browser standard for buttons. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach.

## Exports

### Types

```ts
interface ButtonProps extends Omit<HTMLButtonAttributes, "children" | "form" | "type"> {
  children: Snippet<[string]>;
  left?: Snippet<[string, HTMLButtonElement | undefined]>;
  right?: Snippet<[string, HTMLButtonElement | undefined]>;
  type?: "submit" | "reset" | "button";
  onclick?: MouseEventHandler<HTMLButtonElement> | null;
  form?: HTMLFormElement;
  inactive?: string;
  attach?: Attachment<HTMLButtonElement>;
  element?: HTMLButtonElement;
  styling?: SVSClass;
  variant?: SVSVariant;
}
type ButtonReqdProps = "children";
type ButtonBindProps = "element" | "variant";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=ButtonBasic.svelte
<script lang="ts">
  import { Button } from "svseeds";

  const styling = {
    whole: "py-1 px-4 flex justify-center items-center rounded-md bg-teal-500 cursor-pointer select-none",
    main: "text-white font-medium truncate",
  };
</script>

<Button {styling}>Button</Button>
```
### With Interactive Variant

**Code**

```svelte src=ButtonPract.svelte
<script lang="ts">
  import { Button } from "svseeds";
  import Plus from "@lucide/svelte/icons/plus";

  let { variant = $bindable() } = $props();
  const variantStyle = {
    neutral: "bg-gray-400",
    active: "bg-teal-500",
    inactive: "bg-red-500",
    blue: "bg-blue-500",
    yellow: "bg-yellow-500",
    sky: "bg-sky-500",
  };
  const styling = {
    whole: {
      base: "w-30 h-8 flex flex-nowrap justify-center items-center rounded-md cursor-pointer select-none",
      ...variantStyle,
    },
    main: "px-2 font-medium truncate",
    left: "size-fit",
  };
</script>

<Button bind:variant {styling}>
  Button
  {#snippet left()}
    <Plus class="stroke-white size-5" />
  {/snippet}
</Button>
```