> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Button

General`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Use `Button` for immediate actions such as submitting a form, saving changes, or opening a surface.

## Examples


### Variants
Use one primary action per view or decision area. Secondary, ghost, and destructive variants reduce or clarify emphasis. Bare preserves button behavior while leaving its visual treatment to consumer classes or styles.
```tsx preview
import { Button } from '@rockshin/tao-ui';

function ButtonVariants() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <Button>Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="bare">Bare</Button>
      <Button variant="destructive">Delete</Button>
    </div>
  );
}

export default ButtonVariants;
```

### Sizes
Use `small` for dense toolbars, `medium` for most actions, and `large` for prominent calls to action.
```tsx preview
import { Button } from '@rockshin/tao-ui';

function ButtonSizes() {
  return (
    <div
      style={{
        display: 'flex',
        flexWrap: 'wrap',
        alignItems: 'center',
        gap: 12,
      }}
    >
      <Button size="small">Small</Button>
      <Button>Medium</Button>
      <Button size="large">Large</Button>
    </div>
  );
}

export default ButtonSizes;
```

### Loading and disabled
Loading buttons set `aria-busy` and prevent repeated interaction. Their icon slot stays mounted, so switching states does not shift the content.
```tsx preview
import { useState } from 'react';
import { Button } from '@rockshin/tao-ui';

function ButtonStates() {
  const [saving, setSaving] = useState(false);

  function save() {
    setSaving(true);
    window.setTimeout(() => setSaving(false), 1200);
  }

  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <Button loading>Loading</Button>
      <Button loading variant="secondary">
        Loading
      </Button>
      <Button disabled>Disabled</Button>
      <Button loading={saving} onClick={save}>
        Save changes
      </Button>
    </div>
  );
}

export default ButtonStates;
```

### Icons and custom loading
Pass a decorative leading icon with `icon`. Explicit SVG dimensions are preserved; unspecified dimensions default to the button's font size. Use `loadingIcon` only when the built-in spinner does not match the surrounding visual language.
```tsx preview
import { Button } from '@rockshin/tao-ui';

function DownloadIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M8 2v8m0 0 3-3m-3 3L5 7M3 13h10"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
        strokeLinejoin="round"
      />
    </svg>
  );
}

function ProgressIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
      <circle cx="3" cy="8" r="1.25" />
      <circle cx="8" cy="8" r="1.25" opacity="0.65" />
      <circle cx="13" cy="8" r="1.25" opacity="0.35" />
    </svg>
  );
}

function ButtonIcons() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <Button icon={<DownloadIcon />}>Download</Button>
      <Button variant="secondary" icon={<DownloadIcon />}>
        Export
      </Button>
      <Button loading loadingIcon={<ProgressIcon />}>
        Processing
      </Button>
    </div>
  );
}

export default ButtonIcons;
```

### Provider defaults
Buttons inherit `size` and `disabled` from `TaoProvider`. A local prop can override the inherited size.
```tsx preview
import { Button, TaoProvider } from '@rockshin/tao-ui';

function ButtonProviderDefaults() {
  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <div
        style={{
          display: 'flex',
          flexWrap: 'wrap',
          alignItems: 'center',
          gap: 12,
        }}
      >
        <TaoProvider size="small">
          <Button>Inherited small</Button>
          <Button size="large" variant="secondary">
            Local large
          </Button>
        </TaoProvider>
      </div>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
        <TaoProvider disabled>
          <Button>Provider disabled</Button>
          <Button variant="secondary">Also disabled</Button>
        </TaoProvider>
      </div>
    </div>
  );
}

export default ButtonProviderDefaults;
```

### Semantic customization
Customize the stable `root` part without depending on private selectors.
```tsx preview
import { Button } from '@rockshin/tao-ui';

function CustomizedButton() {
  return (
    <Button
      classNames={{ root: 'checkout-button' }}
      styles={{ root: { minWidth: 0, width: '100%', maxWidth: 160 } }}
    >
      Checkout
    </Button>
  );
}

export default CustomizedButton;
```

### Native form actions
Submit and reset use native form semantics; no network request is sent.
```tsx preview
import { useState } from 'react';
import { Button, Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [result, setResult] = useState('');
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setResult(String(new FormData(e.currentTarget).get('name')));
      }}
      onReset={() => setResult('')}
    >
      <Stack direction="vertical">
        <Input name="name" aria-label="Name" defaultValue="Alex" required />
        <Stack>
          <Button type="submit" variant="primary">
            Save
          </Button>
          <Button type="reset">Reset</Button>
        </Stack>
        <output aria-live="polite">
          {result ? `Saved: ${result}` : 'Edit and save'}
        </output>
      </Stack>
    </form>
  );
}
```

### Icon-only buttons
Provide a name with aria-label and hide decorative icons from assistive technology.
```tsx preview
import { useState } from 'react';
import { Button } from '@rockshin/tao-ui';
export default function Example() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <Button aria-label="Add item" onClick={() => setCount(count + 1)}>
        <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
          <path d="M8 2v12M2 8h12" stroke="currentColor" />
        </svg>
      </Button>
      <output aria-live="polite"> {count} items</output>
    </div>
  );
}
```

### Provider defaults and overrides
Set shared size and disabled defaults, then override a single button.
```tsx preview
import { Button, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <TaoProvider size="small" disabled>
      <Stack>
        <Button>Inherited disabled</Button>
        <Button disabled={false}>Available</Button>
        <Button disabled={false} size="large">
          Large override
        </Button>
      </Stack>
    </TaoProvider>
  );
}
```

## API


### [#](#button)Button



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Prevents interaction. Inherits from TaoProvider. | `boolean | undefined` | `-` |
| children | Button label or inline content. | `ReactNode` | `-` |
| variant | Visual emphasis for the action. | `"primary" | "secondary" | "ghost" | "destructive" | "bare" | undefined` | `primary` |
| size | Control height and horizontal spacing. Inherits from TaoProvider. | `TaoSize | undefined` | `-` |
| loading | Shows the loading icon, sets aria-busy, and prevents interaction. | `boolean | undefined` | `-` |
| icon | Left-leading decorative icon (non-loading state). | `ReactNode` | `-` |
| loadingIcon | Icon shown while loading. Defaults to a built-in spinner. | `ReactNode` | `-` |
| classNames | Semantic class overrides keyed by ButtonSemanticPart. | `Partial<Record<"root", string>> | undefined` | `-` |
| styles | Semantic style overrides keyed by ButtonSemanticPart. | `Partial<Record<"root", CSSProperties>> | undefined` | `-` |

