# Button

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

Source: https://webjs.dev/ui/docs/components/button

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { ArrowUpIcon } from '#lib/ui/lucide.ts';

export default function ButtonDemo() {
  return html`
    <div class="flex flex-wrap items-center gap-2 md:flex-row">
      <button type="button" data-slot="button" class=${buttonClass({ variant: 'outline' })}>Button</button>
      <button type="button" data-slot="button" aria-label="Submit" class=${buttonClass({ variant: 'outline', size: 'icon' })}>${ArrowUpIcon()}</button>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add button
```

### Copy and paste the following code into your project.

````ts title="components/ui/button.ts"
/**
 * Button: styled native `<button>`. Tier-1 class helper. Compose with a
 * real `<button>` (or `<a>` for link-styled buttons) so form submission,
 * focus, keyboard activation, and screen-reader semantics all "just work".
 *
 * shadcn parity:
 *   Button (variant: default | destructive | outline | secondary | ghost | link)
 *         (size:    default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg)
 *                                            → buttonClass({ variant, size })
 *
 * shadcn React's `asChild` (Slot) prop has no equivalent here: just call
 * `buttonClass(...)` and spread the classes onto whatever element you want.
 *
 * A11y (required for accessible output): an icon-only button (the `icon`,
 * `icon-xs`, `icon-sm`, `icon-lg` sizes) has no visible text, so it MUST
 * carry an accessible name via aria-label (or aria-labelledby). A button
 * that opens an overlay should also set aria-haspopup and aria-expanded.
 * Native <button> focus and keyboard activation are already correct.
 *
 * Design tokens used: --primary, --primary-foreground, --destructive,
 * --secondary, --secondary-foreground, --accent, --accent-foreground,
 * --background, --input, --ring.
 *
 * @example
 * ```html
 * <button class=${buttonClass()} type="submit">Save</button>
 * <button class=${buttonClass({ variant: 'outline', size: 'sm' })}>Cancel</button>
 * <button class=${buttonClass({ size: 'icon' })} aria-label="Settings">⚙</button>
 * <a class=${buttonClass({ variant: 'link' })} href="/about">About</a>
 * ```
 */
import { cn } from '../lib/utils.ts';

// Base form (#1666): the semantic `cn-button*` names carry the look, and
// the style named in components.json supplies it when the file is installed
// (styles/style-<name>.css, baked by `add`). What stays inline is the layout
// shadcn's base form keeps inline in every style.
//
// The default new-york style puts cursor-pointer on `cn-button`, so every
// variant gets the right hover affordance. Native <button> defaults to the OS
// arrow cursor in Chromium and Firefox, and shadcn's modern Button has
// gravitated toward an explicit cursor-pointer in the real world (see the open
// issue shadcn-ui/ui#1791). disabled:pointer-events-none below already
// suppresses the cursor on a disabled button.
const BASE =
  "cursor-pointer gap-2 rounded-md text-sm font-medium focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&_svg:not([class*='size-'])]:size-4 group/button inline-flex shrink-0 items-center justify-center whitespace-nowrap transition-all outline-none select-none disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0";

const VARIANTS = {
  default: 'bg-primary text-primary-foreground hover:bg-primary/90',
  destructive: 'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40',
  outline: 'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50',
  secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
  ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
  link: 'text-primary underline-offset-4 hover:underline',
} as const;

const SIZES = {
  default: 'h-9 px-4 py-2 has-[>svg]:px-3',
  xs: "h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
  sm: 'h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5',
  lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
  icon: 'size-9',
  'icon-xs': "size-6 rounded-md [&_svg:not([class*='size-'])]:size-3",
  'icon-sm': 'size-8',
  'icon-lg': 'size-10',
} as const;

export type ButtonVariant = keyof typeof VARIANTS;
export type ButtonSize = keyof typeof SIZES;

export interface ButtonClassOptions {
  variant?: ButtonVariant;
  size?: ButtonSize;
}

/** Compose Tailwind classes for a button. Stable shape: object-arg, both optional. */
export function buttonClass(opts: ButtonClassOptions & { className?: string } = {}): string {
  const variant = opts.variant ?? 'default';
  const size = opts.size ?? 'default';
  return cn(BASE, VARIANTS[variant], SIZES[size], opts.className);
}

/**
 * shadcn's name for {@link buttonClass}, so shadcn code ports verbatim
 * (`buttonVariants({ ... })` is shadcn's `cva` export for `Button`). Like cva, it
 * merges a `className` into the result.
 */
export function buttonVariants(opts: ButtonClassOptions & { className?: string } = {}): string {
  return buttonClass(opts);
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { buttonClass } from '#components/ui/button.ts';
```

```ts
<button class=${buttonClass({ variant: 'outline' })}>Button</button>
```

## Cursor

Tailwind v4 [switched](https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor) from `cursor: pointer` to `cursor: default` for the button component.

If you want to keep the `cursor: pointer` behavior, add the following code to your CSS file:

```css title="styles/globals.css"
@layer base {
  button:not(:disabled),
  [role="button"]:not(:disabled) {
    cursor: pointer;
  }
}
```

## Size

Use the `size` option to change the size of the button.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { ArrowUpRightIcon } from '#lib/ui/lucide.ts';

export default function ButtonSize() {
  return html`
    <div class="flex flex-col items-start gap-8 sm:flex-row">
      <div class="flex items-start gap-2">
        <button type="button" data-slot="button" class=${buttonClass({ variant: 'outline', size: 'xs' })}>Extra Small</button>
        <button type="button" data-slot="button" aria-label="Submit" class=${buttonClass({ variant: 'outline', size: 'icon-xs' })}>${ArrowUpRightIcon()}</button>
      </div>
      <div class="flex items-start gap-2">
        <button type="button" data-slot="button" class=${buttonClass({ variant: 'outline', size: 'sm' })}>Small</button>
        <button type="button" data-slot="button" aria-label="Submit" class=${buttonClass({ variant: 'outline', size: 'icon-sm' })}>${ArrowUpRightIcon()}</button>
      </div>
      <div class="flex items-start gap-2">
        <button type="button" data-slot="button" class=${buttonClass({ variant: 'outline' })}>Default</button>
        <button type="button" data-slot="button" aria-label="Submit" class=${buttonClass({ variant: 'outline', size: 'icon' })}>${ArrowUpRightIcon()}</button>
      </div>
      <div class="flex items-start gap-2">
        <button type="button" data-slot="button" class=${buttonClass({ variant: 'outline', size: 'lg' })}>Large</button>
        <button type="button" data-slot="button" aria-label="Submit" class=${buttonClass({ variant: 'outline', size: 'icon-lg' })}>${ArrowUpRightIcon()}</button>
      </div>
    </div>
  `;
}
```

## Default

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function ButtonDefault() {
  return html`
    <button type="button" data-slot="button" class=${buttonClass()}>Button</button>
  `;
}
```

## Outline

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function ButtonOutline() {
  return html`
    <button type="button" data-slot="button" class=${buttonClass({ variant: 'outline' })}>Outline</button>
  `;
}
```

## Secondary

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function ButtonSecondary() {
  return html`
    <button type="button" data-slot="button" class=${buttonClass({ variant: 'secondary' })}>Secondary</button>
  `;
}
```

## Ghost

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function ButtonGhost() {
  return html`
    <button type="button" data-slot="button" class=${buttonClass({ variant: 'ghost' })}>Ghost</button>
  `;
}
```

## Destructive

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function ButtonDestructive() {
  return html`
    <button type="button" data-slot="button" class=${buttonClass({ variant: 'destructive' })}>Destructive</button>
  `;
}
```

## Link

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

export default function ButtonLink() {
  return html`
    <button type="button" data-slot="button" class=${buttonClass({ variant: 'link' })}>Link</button>
  `;
}
```

## Icon

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { CircleFadingArrowUpIcon } from '#lib/ui/lucide.ts';

export default function ButtonIcon() {
  return html`
    <button type="button" data-slot="button" aria-label="Upgrade" class=${buttonClass({ variant: 'outline', size: 'icon' })}>${CircleFadingArrowUpIcon()}</button>
  `;
}
```

## With Icon

Remember to add the `data-icon="inline-start"` or `data-icon="inline-end"` attribute to the icon for the correct spacing.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { GitBranchIcon } from '#lib/ui/lucide.ts';

export default function ButtonWithIcon() {
  return html`
    <button type="button" data-slot="button" class=${buttonClass({ variant: 'outline', size: 'sm' })}>${GitBranchIcon()} New Branch</button>
  `;
}
```

## Rounded

Use the `rounded-full` class to make the button rounded.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { cn } from '#lib/utils/cn.ts';
import { ArrowUpIcon } from '#lib/ui/lucide.ts';

export default function ButtonRounded() {
  return html`
    <div class="flex flex-col gap-8">
      <button type="button" data-slot="button" aria-label="Scroll up" class=${cn(buttonClass({ variant: 'outline', size: 'icon' }), 'rounded-full')}>${ArrowUpIcon()}</button>
    </div>
  `;
}
```

## Spinner

Render a `spinner()` inside the button to show a loading state, and mark the button `disabled` with `aria-busy="true"` while it waits.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { spinner } from '#components/ui/spinner.ts';

export default function ButtonSpinner() {
  return html`
    <div class="flex gap-2">
      <button type="button" data-slot="button" disabled aria-busy="true" class=${buttonClass({ variant: 'outline' })}>
        ${spinner({ decorative: true })}
        Generating
      </button>
      <button type="button" data-slot="button" disabled aria-busy="true" class=${buttonClass({ variant: 'secondary' })}>
        Downloading
        ${spinner({ decorative: true })}
      </button>
    </div>
  `;
}
```

## Button Group

To create a button group, use the `buttonGroupClass()` helper. See the [Button Group](https://webjs.dev/ui/docs/components/button-group) documentation for more details.

## As Link

A class helper styles any element, so a link that looks like a button is a link with the button's classes.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';

// shadcn's asChild renders the child element with the button's classes.
// A class helper does the same with no wrapper: put it on the link.
export default function ButtonAsChild() {
  return html`<a href="/login" data-slot="button" class=${buttonClass()}>Login</a>`;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

## API Reference

### buttonClass

`buttonClass()` returns the classes for a button. Put them on a native `<button>`, or on any element that should look like one. `buttonVariants()` is an alias of `buttonClass()` that also merges a `className`.

| Option | Type | Default |
| --- | --- | --- |
| `variant` | `"default" \| "outline" \| "ghost" \| "destructive" \| "secondary" \| "link"` | `"default"` |
| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"default"` |
