Button

v4.0.1

Ready for Production

Catalyst Button extends the native <button> element with built-in CVA variants, design tokens, and accessibility defaults — giving you a production-ready button with zero configuration.

Installation

Install the Button primitive:

npm install @pmi/catalyst-button

import { Button, ButtonLabel } from '@pmi/catalyst-button';

Variants

The three core variants provide different levels of visual emphasis for application contexts.

Danger

Use the danger prop for destructive or warning actions across all variants.

Disabled

Disabled state applies to all variants and sizes, visually indicating non-interactivity.

Sizes

Four size options including extra-small for compact interfaces.

Common Patterns

With Icons

Use any icon from @pmi/catalyst-icons in leading, trailing, both, or icon-only positions.

As Child

Use asChild to render the Button as a different element (e.g., <a>) while retaining all styles and behaviors.

Stylized Variant

ButtonStylized renders a hollow gradient border using CSS mask composition — same size and asChild API as Button, five gradient color schemes.

Membership Variant

ButtonMembershipRoot is a specialized button for premium membership CTAs with a tangerine-to-violet gradient hover effect and icon/label sub-components.

API Reference

Button

The root Button primitive with full variant and state control. Accepts all standard React button attributes (onClick, type, aria-*, etc.).

Extends React.ButtonHTMLAttributes<HTMLButtonElement> for native button behavior and accessibility.

ButtonLabel

Text label part for button content with size-aware positioning. Accepts all standard React span attributes (className, id, data-*, etc.).

Extends React.HTMLAttributes<HTMLSpanElement> for flexible label rendering.

ButtonMembershipRoot

Premium membership CTA button with gradient hover effect. Accepts all standard React button attributes.

Extends React.ButtonHTMLAttributes<HTMLButtonElement> for native button behavior and accessibility.

ButtonMembershipIcon

Size-aware icon container for ButtonMembershipRoot. Scales with the button size. Accepts all standard React span attributes.

ButtonMembershipLabel

Text label for ButtonMembershipRoot with size-aware typography and gradient text effect. Accepts all standard React span attributes.

Accessibility

Keyboard Interactions

ARIA

• Use <button> elements. Screen readers do not recognize <div> or <img> as interactive controls.
• Provide aria-label on icon-only buttons where no visible text label exists.
• Use links for navigation and buttons for actions. Styling does not change the underlying semantics or keyboard behavior.
  • Buttons should be activated by Space and Enter keys.
  • Links styled as buttons should only be activated by the Enter key.
• The focus ring uses a 2px outline with offset, mapped to pmi-off-black-800 (light) and white (dark). Contrast meets WCAG 2.2 Level AA standards.

See the APG Button Pattern and MDN Button Role for the full specification.

Choosing the Right Component

• Form submissions — save, submit, reset.
• In-page actions — open a modal, toggle a panel, trigger a calculation.
• Destructive operations — delete or remove, paired with the danger prop.
• Confirming choices — accept terms, complete a step.

Button vs. Link

Ask: "Does this take the user somewhere, or does it do something?"

• Navigates to a URL → use a Link.
• Performs an action → use a Button.

Need a link that looks like a button? Use asChild:

<Button asChild>
  <a href="/settings">Go to Settings</a>
</Button>

When to Use Something Else

• Inline text navigation → Link
• Stateful toggles (e.g., bookmark on/off) → toggle or icon button with aria-pressed
• Navigation menus → dedicated nav component

Variant Selection

Related

• Link