# Button

> The primary action primitive. Gold CTA by default, three sizes, six variants, polymorphic via a single `variant` prop.

- Category: primitive
- Status: stable (since 0.1.0)
- A11y pattern: https://www.w3.org/WAI/ARIA/apg/patterns/button/
- Tokens: --cta-background, --cta-foreground, --foreground-primary, --background-secondary, --dur-fast, --ease-snap
- Playground: https://design.freecodecamp.org/playground#button
- npm dependencies: `react@>=18 <20`
- Registry dependencies: [theme](https://design.freecodecamp.org/registry/theme.md)
- Files:
  - `Button.tsx` → `src/ui/button/Button.tsx` (raw: https://design.freecodecamp.org/registry/button/Button.tsx)
  - `button.css` → `src/ui/button/button.css` (raw: https://design.freecodecamp.org/registry/button/button.css)

## Install (copy source)

1. Ensure the theme is installed once per project - tokens.css + base.css imported globally, fonts available. See https://design.freecodecamp.org/registry/theme.md and https://design.freecodecamp.org/registry/starter.md.
2. Copy the files below into `src/ui/button/` (adjust to your project layout) and import the CSS once from your global stylesheet, e.g. `@import './ui/button/button.css';`.
3. Colors, spacing and type come from tokens - tailor the component by editing the copied source; recolour by editing tokens.css, not the component CSS.

## Usage

Buttons trigger immediate actions. Use a link for navigation, a button for
anything that changes state on the current page.

## Keyboard

| Key           | Action                                     |
| ------------- | ------------------------------------------ |
| Space / Enter | Activates the button.                      |
| Tab           | Moves focus to the next focusable element. |

## Accessibility

Renders a native `<button>` element. The focus ring is 3 px solid
`--blue-mid` - the same ring every interactive primitive uses.
Disabled buttons forward `aria-disabled="true"` and drop out of the
tab order.

## Example

```tsx
import { Button } from './ui/button/Button';

export function Actions() {
  return (
    <div style={{ display: 'flex', gap: 12 }}>
      <Button variant="cta">Start curriculum</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="danger">Dangerous</Button>
      <Button variant="ghost">Ghost</Button>
    </div>
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | no | `default` |  |
| `size` | `enum` | no | `md` |  |
| `block` | `boolean` | no | `false` |  |
| `isLoading` | `boolean` | no | `false` |  |

## Source: Button.tsx

```tsx
import React, { forwardRef } from 'react';

export type ButtonVariant =
  | 'default'
  | 'cta'
  | 'danger'
  | 'info'
  | 'ghost'
  | 'link';
export type ButtonSize = 'sm' | 'md' | 'lg';

export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant;
  size?: ButtonSize;
  block?: boolean;
  isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      variant = 'default',
      size = 'md',
      block = false,
      isLoading = false,
      className = '',
      disabled,
      children,
      ...rest
    },
    ref
  ) => {
    const classes = [
      'btn',
      variant !== 'default' && `btn--${variant}`,
      size !== 'md' && `btn--${size}`,
      block && 'btn--block',
      className
    ]
      .filter(Boolean)
      .join(' ');
    return (
      <button
        ref={ref}
        className={classes}
        disabled={disabled || isLoading}
        aria-busy={isLoading ? true : undefined}
        {...rest}
      >
        {isLoading && <span className='btn__spinner' aria-hidden='true' />}
        {children}
      </button>
    );
  }
);
Button.displayName = 'Button';
```

## Source: button.css

```css
.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  font-family: var(--font-sans);
  font-size: var(--fs-md);
  font-weight: var(--fw-regular);
  line-height: var(--lh-base);
  padding: 6px 14px;
  border: var(--border-width-thick) solid var(--foreground-secondary);
  background: var(--background-quaternary);
  color: var(--foreground-secondary);
  text-decoration: none;
  cursor: pointer;
  transition:
    background-color 120ms,
    color 120ms,
    border-color 120ms;
  position: relative;
}
.btn:hover {
  background: var(--foreground-primary);
  color: var(--background-primary);
}
.btn:active::before {
  content: '';
  position: absolute;
  inset: 0;
  background: var(--gray-90);
  opacity: 0.2;
}
.btn:disabled,
.btn[aria-disabled='true'] {
  opacity: 0.5;
  cursor: not-allowed;
}

.btn--cta {
  background: var(--cta-background);
  color: var(--cta-foreground);
  border-color: var(--cta-background);
}
.btn--cta:hover {
  background: var(--cta-background);
  color: var(--cta-foreground);
  filter: brightness(1.08);
}

.btn--danger {
  border-color: var(--danger-color);
  background: var(--danger-background);
  color: var(--danger-color);
}
.btn--danger:hover {
  background: var(--danger-color);
  color: var(--danger-background);
}

.btn--info {
  border-color: var(--highlight-color);
  background: var(--highlight-background);
  color: var(--highlight-color);
}
.btn--info:hover {
  background: var(--highlight-color);
  color: var(--highlight-background);
}

.btn--ghost {
  border-color: transparent;
  background: transparent;
  color: var(--foreground-secondary);
}
.btn--ghost:hover {
  background: var(--background-tertiary);
  color: var(--foreground-primary);
}

.btn--link {
  border-color: transparent;
  background: transparent;
  color: var(--highlight-color);
  text-decoration: underline;
  padding: 2px 4px;
}
.btn--link:hover {
  background: transparent;
  color: var(--foreground-primary);
}

.btn--sm {
  padding: 4px 10px;
  font-size: var(--fs-sm);
  border-width: var(--border-width-default);
}
.btn--lg {
  padding: 10px 18px;
  font-size: var(--fs-lg);
}
.btn--block {
  display: flex;
  width: 100%;
}

.btn[aria-busy='true'] {
  cursor: progress;
}
.btn__spinner {
  display: inline-block;
  width: 1em;
  height: 1em;
  border: 2px solid currentColor;
  border-right-color: transparent;
  border-radius: 50%;
  animation: fcc-spin 800ms linear infinite;
  vertical-align: -0.125em;
}
@keyframes fcc-spin {
  to {
    transform: rotate(360deg);
  }
}
```

## HTML / vanilla variant

```html
<button class="btn btn--cta">Start curriculum</button>
<button class="btn">Secondary</button>
<button class="btn btn--danger">Dangerous</button>
<button class="btn btn--ghost">Ghost</button>
```

Interactive behaviours for plain HTML come from the vanilla runtime (data-uikit-* attributes): https://design.freecodecamp.org/registry/vanilla.md - or download https://design.freecodecamp.org/cdn/uikit.global.js once and self-host it (do not hotlink).

## For coding agents

This library is distributed as copyable source, not an npm package. Start at https://design.freecodecamp.org/registry/starter.md, discover components via https://design.freecodecamp.org/llms.txt, and copy files into the consuming project. Keep token names intact; recolour by editing the copied tokens.css.