Button · Smallest

Sizes

The default size is md.

Variants

Primary is the default. Give each group of actions one primary; supporting actions use secondary or tertiary.

import { Button } from "@smallest-inc/ui";

export default function ButtonVariants() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button variant="primary">Deploy</Button>
      <Button variant="secondary">Cancel</Button>
      <Button variant="tertiary">Preview</Button>
      <Button variant="brand">Upgrade</Button>
      <Button variant="danger">Delete</Button>
      <Button variant="danger-subtle">Remove</Button>
      <Button variant="transparent">Skip</Button>
    </div>
  );
}

All variants and sizes in comparison

import { Button } from "@smallest-inc/ui";

const variants = ["primary", "secondary", "tertiary", "brand", "danger", "danger-subtle", "transparent"] as const;
const sizes = ["sm", "md", "lg", "xl"] as const;

export default function ButtonComparison() {
  return (
    <div className="flex flex-col items-start gap-4">
      {sizes.map((size) => (
        <div key={size} className="flex items-center gap-3">
          {variants.map((variant) => (
            <Button key={variant} size={size} variant={variant}>
              Upload
            </Button>
          ))}
        </div>
      ))}
    </div>
  );
}

Shapes

Rounded is the default; pill is for marketing and onboarding surfaces.

Icon only

Pass iconOnly with a text size: xs is 24×24, and sm through xl match the text button heights. Pill makes it a circle. Icon-only buttons need an aria-label that names the action and its target.

import {
  ArrowUpIcon,
  Button,
  CopyIcon,
  SearchIcon,
  SettingsIcon,
  TrashIcon,
} from "@smallest-inc/ui";

export default function ButtonIconOnly() {
  return (
    <div className="flex flex-col items-start gap-4">
      <div className="flex items-center gap-3">
        <Button iconOnly aria-label="Upload file" size="xs">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file" size="sm">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file" size="lg">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file" size="xl">
          <ArrowUpIcon />
        </Button>
      </div>
      <div className="flex items-center gap-3">
        <Button iconOnly aria-label="Upload file" shape="pill" size="xs">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file" shape="pill" size="sm">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file" shape="pill">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file" shape="pill" size="lg">
          <ArrowUpIcon />
        </Button>
        <Button iconOnly aria-label="Upload file" shape="pill" size="xl">
          <ArrowUpIcon />
        </Button>
      </div>
      <div className="flex items-center gap-3">
        <Button iconOnly aria-label="Open settings">
          <SettingsIcon />
        </Button>
        <Button iconOnly aria-label="Search agents" variant="secondary">
          <SearchIcon />
        </Button>
        <Button iconOnly aria-label="Copy agent ID" variant="tertiary">
          <CopyIcon />
        </Button>
        <Button iconOnly aria-label="Delete agent" variant="danger-subtle">
          <TrashIcon />
        </Button>
      </div>
    </div>
  );
}

Prefix and suffix

Place icons directly beside the label. Source order sets the side, and the padding on that side tightens by 2px.

import { Button, ChevronRightIcon, PlusIcon } from "@smallest-inc/ui";

export default function ButtonPrefixSuffix() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button>
        <PlusIcon />
        New agent
      </Button>
      <Button variant="secondary">
        Continue
        <ChevronRightIcon />
      </Button>
      <Button variant="tertiary">
        <PlusIcon />
        Add step
        <ChevronRightIcon />
      </Button>
    </div>
  );
}

Keys

Show the shortcut that runs the action. A string is one chip; an array is one chip per key.

Disabled

import { Button } from "@smallest-inc/ui";

export default function ButtonDisabled() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button disabled>Deploy</Button>
      <Button variant="secondary" disabled>
        Cancel
      </Button>
      <Button variant="tertiary" disabled>
        Preview
      </Button>
      <Button variant="danger" disabled>
        Delete
      </Button>
    </div>
  );
}

Link

Link variants sit inline with text. Pass render={<a href />} when the button navigates.

View pricing Read the docs

import { Button } from "@smallest-inc/ui";

export default function ButtonLink() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <Button variant="link" render={<a href="#pricing" />}>
        View pricing
      </Button>
      <Button variant="link-primary" render={<a href="#docs" />}>
        Read the docs
      </Button>
      <Button variant="link-danger">Revoke key</Button>
    </div>
  );
}

Best practices

When to use

Use Button for actions that change something: save, deploy, delete. When it navigates to a new URL, use a link variant with render={<a href />}.
Use Split Button when one action is the clear default and a few close variants belong next to it. Use Dropdown when the actions are unrelated.
Give each group of actions one primary. Supporting actions use secondary or tertiary; keep brand for upgrade and marketing moments.
Use Toggle or Switch when the control holds a persistent state rather than running an action.

Behavior

Disable a button only when the action is impossible right now, such as missing input or permission, and say why nearby or in a Tooltip.
Pass keys only for a shortcut the product actually binds. The chip is the hint, not the listener. A string is one chip; an array is one chip per key.

Content

Name what happens with Verb + Noun in sentence case: “Deploy agent”, “Invite member”, “Rotate key”. Avoid bare verbs like “Submit” and generic confirms like “OK”.
Destructive actions use danger or danger-subtle and name the object: “Delete agent”, not “Delete”.

Accessibility

Icon-only buttons need an aria-label that names the action and its target, like “Copy agent ID”, not the icon, like “Copy”.
Do not set aria-label on a button with visible text; it replaces the label for screen readers.
The keys chip is decorative. The label stays the accessible name.